Skip Navigation
Expand
Element Manager current capabilities
Answer ID 10656   |   Last Review Date 04/14/2020

How to use Element Manager REST APIs? 

Environment:

Element Manager, REST APIs

Issue:

We want to start consuming the Element Manager REST APIs to automate the transport of Oracle Service Cloud configurations across sites/interfaces.

Resolution:.

Element Manager provides REST APIs to programmatically automate transport of configurations across B2C service sites/interfaces. All Element-Manager APIs are now exposed as public REST endpoints so that users can invoke them in a sequence to achieve the export/import functionality. 

The REST APIs swagger documentation can be accessed via URL like this:
https://<siteurl>/AgentWeb/elementManager/swaggerUI.

The APIs can be categorized as following:

  1. Authentication APIs
  2. Search APIs and Export APIs
  3. Import APIs


A) Authentication APIs 

A public API authorization token is required to invoke the Element-Manager export/import public APIs that can be generated using the following two authentication endpoints:

Expand this section for more information and examples.

1. POST /securityservice/authentication/authToken
This API is used to authenticate the user to element manager and the response will be an authentication token. The endpoint for authToken API requires username, password and an interfaceUrl to be passed as request body JSON. The response will contain a token field that has the required public API authorization token. The endpoint is deprecated and its encouraged to use the new JWT based authentication endpoint for token generation.

Click here to expand example.

Request Headers:
interfaceUrl: <<interfaceUrl>> (eg. http://<site-name>/cgi-bin/<interface>.cfg)

Request body: 
{"username": "username", "password": "password", "interfaceUrl": "http://<site-name>/cgi-bin/<interface>.cfg"}

Response body:

   "description":"Authorization token",
   "token":"eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk="
}

2. POST /elementmanager/authentication/authToken
This API is used to authenticate the user to element manager based on JWT and the response will be an authentication token.  The endpoint requires JWT token as Authorization header. The response will contain a token field that has the required public API authorization token. See detailed documentation on the required OAuth configuration setup and JWT token generation.

Click here to expand example.

Request Headers:
Authorization: Bearer JwtToken
interfaceUrl: interfaceUrl (http://<site-name>/cgi-bin/<interface>.cfg)

Response body:

   "description":"Authorization token",
   "token":"eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk="
}


B) Search and Export APIs
To perform an element-manager export action using element-manager public APIs, an authToken should be first generated using an authentication endpoint. Once authToken is generated, export endpoints can be hit with the generated authToken added as a request header named USERSESSION. An element-manager import action can be done using the following APIs:

  1. Search Items POST /elementmanager/search/EMElements
  2. Create Package POST /elementmanager/export/EMPackages
  3. Get Status GET /elementmanager/export/EMPackages/{id}
  4. Download Package GET /elementmanager/export/EMPackages/download/{id}


Expand this section for more information and examples.

1. Search Items POST /elementmanager/search/EMElements
This API is used to execute search based on search criteria and the response will be a list of matching items.  The endpoint request body can contain the following attributes:

  • limit: the attribute can be used to limit the number of resultant items eg. 100
  • searchTypes: an array of item types against which the search will be performed. eg. [Report, Workspace]
  • searchString: the search string to match the item-name (contains search)
  • filter: apart from search string, we can add more complex search filters using this attribute

A simple contains search can be made using the searchString attribute. eg. See request body example (i). It shows a simple search based on a searchString and searchType. The search response will contain item(s) that matches the given name and type.

The filter attribute is a complex type that contains a filterTerm and a filterOperator. The filterTerm field represents a search condition. The field can have three sub fields named name, condition and value. The supported filterTerm-name field values are Id, ParentId, label and typeId. And the supported filterTerm-condition field values are isNotNull, isNull, isEqual, isNotEqual, isIn, isNotIn and isGreater. When using filterTerm, the value of filterOperator attribute should be "none". See request body example (ii).

The filterOperator can be used to combine multiple search conditions. The supported filterOperator field values are none, and, or. See request body example (iii). In this example, the search response will contain an item that exactly matches the name Basic Report and also has the parent id 104227.

The search response will contain the required item-id that is required by the create package export endpoint.

Click here to expand example.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk= (the sample token used here should be replaced by an actual token that could be generated using one of the element-manager provided authentication endpoints)

Request body: 
example (i) Simple contains search using searchString field

   "limit":100,
   "searchTypes":[ 
      "Report"
   ],
   "searchString":"Custom2Reports"
}

example (ii)
Single condition search using filterTerm

   "searchTypes":[ 
      "Report"
   ],
   "filter":{ 
      "filterOperator":"none",
      "filterTerm":{ 
         "name":"Id",
         "condition":"isGreater",
         "value":101970
      }
   }
}

example (iii) Complex search combining multiple conditions using filterOperator

   "limit":100,
   "searchTypes":[ 
      "Report"
   ],
   "startingIndex":0,
   "filter":{ 
      "filterOperator":"and",
      "children":[ 
         { 
            "filterOperator":"none",
            "filterTerm":{ 
               "name":"Id",
               "condition":"isGreater",
               "value":101970
            }
         },
         { 
            "filterOperator":"none",
            "filterTerm":{ 
               "name":"label",
               "condition":"isEqual",
               "value":"Custom2Reports"
            }
         }
      ]
   }
}

Response body:

   "description":"Search results",
   "resultSet":[ 
      { 
         "type":"Report",
         "hasMoreItems":false,
         "items":[ 
            { 
               "id":104227,
               "type":{ 
                  "id":142,
                  "name":"AnalyticsFolder"
               },
               "name":"AgentBrowser",
               "level":1,
               "hasMoreChildren":true,
               "sequence":0,
               "children":[ 
                  { 
                     "id":101974,
                     "type":{ 
                        "id":1,
                        "name":"Report"
                     },
                     "name":"Custom2Reports",
                     "level":2,
                     "hasMoreChildren":false,
                     "sequence":30,
                     "children":[ 

                     ],
                     "isParent":false
                  }
               ],
               "isParent":true
            }
         ]
      }
   ]
}

2. Create Package POST /elementmanager/export/EMPackages
This API is used to select items for export. The endpoint for Create Package API requires a package name and an array of items in which each item entry should contain an item-id and an item-type. The element-manager supported item types as of now are:

  • Report
  • Workspace
  • AddIn
  • NavigationSet
  • CustomObject
  • CustomAttribute
  • StandardText
  • Variable
  • ObjectEventHandler
  • ConfigurationSettings
  • MessageBase
  • ConfigBase

The item-id of an item can be identified using the search API. The create package action is asynchronous and thus the response will contain an initial status and a package-id that can be later used to track the status of the export or download the package.

Click here to expand example.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk=

Request body: 

   "name":"SamplePackage",
   "items":[ 
      { 
         "id":"101974",
         "type":"Report"
      }
   ]
}

Response body:

   "description":"Prepare package for export",
   "id":100170,
   "name":"SamplePackage",
   "status":{ 
      "code":"1",
      "description":"Export prepare start"
   },
   "href":"http://abc.com/AgentWeb/api/elementmanager/export/EMPackages/100168"
}


3. Get Export Status GET /elementmanager/export/EMPackages/{id}

This API is used to get the status of an export action. The endpoint for Get Export Status API requires the package-id as a path parameter. The response will contain a package status. The package status can be any of the following:

  • Export prepare start (1)
  • Export prepare in progress (2)
  • Export prepare complete (3)
  • Export prepare failed (7)
  • Export start (4)
  • Export complete (5)
  • Export failed (6)

The package will be ready for download once the package status becomes Export complete. In case of any errors during export, the status will be shown as Export prepare failed or Export failed. The Export prepare failed error occurs when element-manager fails to properly identify dependencies of selected items. The Export failed error occurs when element-manager fails to generate the required zip file.

Click here to expand example.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk=

Response body:

   "description":"Prepare package for export",
   "id":100170,
   "name":"SamplePackage",
   "status":{ 
      "code":"1",
      "description":"Export prepare start"
   },
   "href":"http://abc.com/AgentWeb/api/elementmanager/export/EMPackages/100170"
}


In addition to the package specific Get Export Status, element-manager also provides another endpoint which just gives the status of the last 100 export actions:  
               Get All Package Status: GET /elementmanager/export/EMPackages

This API is used to get the status of the last hundred available export actions. The endpoint does not require any input parameters. The endpoint response will contain an array of items in which each item represents an export action and its status.

Click here to expand example.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk=

Response body:

   "description":"Collection of packages",
   "items":[ 
      { 
         "id":100170,
         "name":"SamplePackage",
         "status":{ 
            "code":"3",
            "description":"Export prepare complete"
         },
         "href":"http://abc.com/AgentWeb/api/elementmanager/export/EMPackages/100170"
      },
      { 
         "id":100169,
         "name":"SamplePackage",
         "status":{ 
            "code":"7",
            "description":"Export complete"
         },
         "href":"http://abc.com/AgentWeb/api/elementmanager/export/EMPackages/100169"
      }
   ]
}


4. Download Package GET /elementmanager/export/EMPackages/download/{id}
This API is used to download a package. The endpoint for Download Package requires package-id as a path parameter. Once the package status is Export Complete, the package can be downloaded using the endpoint.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk=


C) Import APIs

To perform an element-manager import action using element-manager public APIs, an authToken should be first generated using an authentication endpoint. Once authToken is generated, import endpoints can be hit with the generated authToken added as a request header named USERSESSION. An element-manager import action can be done using the following APIs:

  1. Initiate Import POST /elementmanager/import/EMPackages
  2. Get Status GET /elementmanager/import/EMPackages/{id}
  3. Import\Rollback PATCH /elementmanager/import/EMPackages/{id}
  4. Cancel Import DELETE /elementmanager/import/EMPackages/{id}


Expand this section for more information and examples.

1. Initiate Import POST /elementmanager/import/EMPackages
This API is used to initiate an import action. The endpoint for Initiate Import requires packageContent and name to be passed as request body JSON. The base64 encoded form of the required zip package should be used as the packageContent value and the name field should have some value just for identifying the specific import. The Initiate Import action is asynchronous and the response will contain an import package-id and a getStatus URL with which the status of the same import can be tracked.

Click here to expand example.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk=

Request body:

   "packageContent":"UEsDBBQACAgIAFVbek4AAAAA...BBDwAAAAA=",
   "name":"SampleImportName"
}

Response body:

   "description":"Prepare package for import",
   "id":100002,
   "href":"http://abc.com/AgentWeb/api/elementmanager/import/EMPackages/100002"
}


2. Get Import Status GET /elementmanager/import/EMPackages/{id}

This API is used to get the status of an import action.  The endpoint for Get Import Status API requires the package-id as a path parameter. The response will contain a package status and also item-level status if available. The package status can be any of the following:

  • Import start (1)
  • File upload start (2);
  • File upload complete (3)
  • PreScan start (4)
  • PreScan complete (5)
  • Artifact load start (6)
  • Artifact load in progress (7)
  • Artifact load complete (8)
  • Import complete (10)
  • Rollback start (11)
  • Rollback complete (12)
  • PreScan failed (15)
  • Import failed (17)
  • Rollback failed (18)
  • Import cancelled (20)

The item-level information contains item-stage that can be any of the following:

  • Verification success (2)
  • Artifact creation in progress (3)
  • Artifact created (4)
  • Artifact live (5)
  • Artifact rollback (6)
  • Verification failed (10)

Apart from the artifact creation/live/rollback status, other three item stages belongs to the PreScan phase. The preScan phase is the stage at which all the items associated with an import action will be validated. In case of validation is success, the package-level status will be set to PreScan complete and the individual item-level stage will be set to verification success. The verification success status can occur even with item-level warnings:

  • Report contains Scripts (70)
  • Item contains addins (71)
  • Interface values for variable items will not be exported (72)
  • Rule menu item mapping failed (73)

Likewise, in case of preScan failure, the package-level status would be PreScan failed and the item-level stage would be verification failed. The verification failure reason for every individual item will be shown as validationError. The possible known validation errors are listed below:

  • Item error (2)
  • Unrecognized workspace type (3)
  • Unrecognized workspace field (4)
  • Item definition corrupted (5)
  • No permission (6)
  • Composite item (7)
  • Invalid joins (8)
  • Item exists (9)
  • Schema entries missing (10)
  • Unrecognized column (11)
  • Signature verification failed (14)
  • Menu item mapping failed (15)
  • Dependency missing (18)
  • Unrecognized navset custom object (19)
  • Unrecognized custom attribute dependency (20)
  • Unrecognized object event handler custom object (22)


Click here to expand example.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk=

Request body:

   "packageContent":"UEsDBBQACAgIAFVbek4AAAAA...BBDwAAAAA=",
   "name":"SampleImportName"
}

Response body:

   "description":"State of the import package",
   "id":100002,
   "name":"SampleImportName",
   "status":{ 
      "code":"5",
      "description":"Prescan Complete"
   },
   "items":[ 
      { 
         "id":1000089,
         "elementId":12,
         "name":"CUSTOM_CFG_TEXT_intf",
         "type":"ConfigurationSettings",
         "stage":{ 
            "code":"2",
            "description":"Verification Success"
         },
         "folderPath":"Custom"
      },
      { 
         "id":1000088,
         "elementId":13,
         "name":"CUSTOM_CFG_SITE",
         "type":"ConfigurationSettings",
         "stage":{ 
            "code":"2",
            "description":"Verification Success"
         },
         "folderPath":"Custom"
      }
   ]
}


In addition to the package specific Get Import Status, element-manager also provides another endpoint which just gives the status of the last 100 export actions: Get All Package Status: GET /elementmanager/import/EMPackages

This API is used to get the status of the last hundred available import actions. The endpoint does not require any input parameters. The endpoint response will contain an array of items in which each item represents an import action and its status.

Click here to expand example.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk=

Response body:

   "description":"Collection of packages",
   "items":[ 
      { 
         "id":100004,
         "name":"incident_report",
         "status":{ 
            "code":"15",
            "description":"Prescan failed"
         },
         "href":"http://abc.com/AgentWeb/api/elementmanager/import/EMPackages/100004"
      },
      { 
         "id":100003,
         "name":"incident_report",
         "status":{ 
            "code":"20",
            "description":"Canceled"
         },
         "href":"http://abc.com/AgentWeb/api/elementmanager/import/EMPackages/100003"
      }
   ]
}


3. Import\Rollback PATCH /elementmanager/import/EMPackages
This API is used to either import a package that has already passed the preScan stage(ie. in PreScan Success state) or to rollback an already deployed package that should be in Import Complete state. The endpoint for Import\Rollback requires package-id, action and a permissions array to be passed as request body JSON. 

The action field can be either Import or Rollback. The permissions array can be either left empty or used to assign profile/interface permissions to reports, add-ins and variables.

Request body example (i) represents a sample import action that will use just the default permissions. To override the default permissions from the exported package, the permissions array can be properly populated. The permissions override option is available for reports, add-ins and standardText.

For reports, corresponding to each elementId (elementId can be identified from the getStatus response), an array of profilePermissions can be set. Each profilePermissions entry should contain an array of profileIds and a permission value. The supported permission values are:

  • open (1)
  • edit (2)

For add-ins, the profile/interface permission-ing can be done using the same profilePermissions  array. Here, each profilePermissions entry should contain an array of profileIds and another array of interfaceIds.

For standard-texts. instead of profilePermissions, interfacePermission array can be used to set the required interface visibility flags.

Click here to expand example.

e.g.

   "action":"import",
   "id":"100098",
   "permissions":[ 
      { 
         "elementIds":[ 
            12 //report elementId
         ],
         "profilePermissions":[ //report profile permission
            { 
               "profileIds":[ 
                  7
               ],
               "permission":"edit"
            }
         ]
      },
      { 
         "elementIds":[ 
            13 //add-in elementId
         ],
         "profilePermissions":[ //add-in profile/interface permission
            { 
               "profileIds":[ 
                  7,
                  9
               ],
               "interfaceIds":[ 
                  1
               ]
            }
         ]
      },
      { 
         "elementIds":[ 
            14 //standard-text elementId
         ],
         "interfacePermission":[  //interface visibility
            1,
            2
         ]
      }
   ]
}


Note: As in the above example, the assignment of permissions require IDs of profiles and interfaces. The search API can be used to identify the required IDs.

The getStatus API should be used to track the status of import/rollback actions.

Click here to expand example.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk=

Request body:
example (i): import action

   "action":"import",
   "id":"100002",
   "permissions":[
    ]
}

example (ii): rollback action

   "action":"rollback",
   "id":"100002",
}

Response body:
example (i): import action response


   "description":"Import the package",
   "id":100005,
   "name":"SampleImportName",
   "href":"http://abc.com/AgentWeb/api/elementmanager/import/EMPackages/100005"
}

example (ii): rollback action response

   "description":"Rollback the import package",
   "id":100005,
   "name":"SampleImportName",
   "href":"http://abc.com/AgentWeb/api/elementmanager/import/EMPackages/100005"
}


3. Cancel Import DELETE /elementmanager/import/EMPackages/{id}
This API is used to delete or cancel an existing incomplete import action. The endpoint for Cancel Import requires a package-id as the path parameter. The response will contain the status of cancel action.

Click here to expand example.

Request Headers:
USERSESSION: eyJ0aW1lc3RhbXAiOjE1Njg3MDc1MDg3NTMsInNpZ25hdHVyZSI6IlhZcFNNZ2JoeTROcjVzRmJ0MTEvS1Z3ejkxST0iLCJk=

Response body:

   "description":"Deleting the EM Package",
   "status":{ 
      "code":"19",
      "description":"Deleted"
   }
}


D) Public API Exceptions
The available element-manager public API exception codes are listed below:

Expand this section to see the exceptions list.

  • OSC-EM-EXC-0001: Service exception
  • OSC-EM-EXC-0002: Unauthorized exception
  • OSC-EM-EXC-0003: Invalid input exception
  • OSC-EM-EXC-0004: Missing mandatory field exception
  • OSC-EM-EXC-0005: Profile permissions not required exception
  • OSC-EM-EXC-0006: Another import is in progress exception
  • OSC-EM-EXC-0007: Manifest corrupted exception
  • OSC-EM-EXC-0008: Invalid action requested exception
  • OSC-EM-EXC-0009: Cannot proceed exception
  • OSC-EM-EXC-0010: Export threshold exceeded exception
  • OSC-EM-EXC-0011: API not allowed exception
  • OSC-EM-EXC-0012: Unable to connect exception
  • OSC-EM-EXC-0013: Invalid profile-id exception
  • OSC-EM-EXC-0014: Invalid permission bit exception
  • OSC-EM-EXC-0015: No privilege exception
  • OSC-EM-EXC-0016: Package id not found exception
  • OSC-EM-EXC-0017: Invalid element-id exception
  • OSC-EM-EXC-0018: Invalid interface-id exception
  • OSC-EM-EXC-0019: Profile permission not applicable exception
  • OSC-EM-EXC-0020: Permissions not applicable exception
  • OSC-EM-EXC-0021: Permission configuration not applicable exception


Additional Information:

Element-Manager Public API authentication

Available Languages for this Answer:

Notify Me
The page will refresh upon submission. Any pending input will be lost.