Search

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.

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. 

Click here to expand example.

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.

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.

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.

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.

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=
 

1. Initiate Import POST /elementmanager/import/EMPackages
This API is used to create an import package. 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.

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.

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.

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.

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.

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.

• 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