Workflow

Once API-based systems have been configured in Connect and the corresponding action applied to items in a workbook in Manage, an API Developer user, using the OpenText Core Data Discovery & Risk Insights APIs, retrieves the workbook items and defines the action status as Pending. The designated person then applies the custom action in your external application, and then defines the action status as Completed.

The API-based custom activity workflow is as follows.

  1. Log in to OpenText Core Data Discovery & Risk Insights using the API.

  2. If the access token expires, Refresh the access token.

  3. List the workbooks marked for the custom action.

  4. Update the custom action status to Processing.

  5. Retrieve list of documents in the workbook.

  6. Update the custom activity status to Completed.

CAUTION: When running the curl commands, the curl request must not contain line breaks. Any breaks in the curl request in the syntax and examples here are a result of line wrapping for viewing.

If you copy and paste the contents of the curl commands, you must manually remove line breaks.

Log in to OpenText Core Data Discovery & Risk Insights

Gateway Service: Authentication: /v1/auth/login

Use the /v1/auth/login API to log in to the OpenText Core Data Discovery & Risk Insights environment. You will be returned two tokens, accessToken and refreshToken. The access token is digitally signed by the realm. You can make REST invocations on remote services using the access token. The REST service extracts the access token, verifies the signature of the token, then decides, based on access information within the token, whether to process the request. The access token is short-lived and expires in five minutes. The refresh token transmitted by the Login API allows the application to obtain a new access token after it expires.

Request syntax

curl -X POST "https://<gatewayHost_FQDN>:<port>/v1/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"tenantId\": \"<tenantID>\", \"user\": \"<userEmailAddress>\", \"password\": \"<userPassword>\"}"}"

where,

  • <gatewayHost_FQDN> and <port> are the fully qualified domain name and port of the machine hosting the Marathon gateway.

  • <tenantID> is the name, or ID, of the tenant.

  • <userEmailAddress> is the email address of the user account that was created with the prerequisite permissions for the purpose of using the APIs.

  • <userPassword> is the password for the defined user.

Example request

curl -X POST "https://host-ext01.domain.net:9310/v1/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"tenantId\": \"t1616\", \"user\": \"user@domain.com\", \"password\": \"123abc6D\"}"}"

Example response

{
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiTOKEN",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldTOKEN"
}

Refresh the access token

Gateway Service: Authentication: /v1/auth/token/refresh

If the access token expires, use the /v1/auth/token/refresh API to refresh the access token. When you refresh the token, you are given a new access token and a new refresh token. For any subsequent refreshes, you must use the newer refresh token.

Example syntax

curl -X POST "https://<gatewayHost_FQDN>:<port>/v1/auth/token/refresh" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"tenantId\": \"<tenantID>\", \"refreshToken\": \"<refreshToken>\", \"caller\": \"string\"}"

where,

  • <gatewayHost_FQDN> and <port> are the fully qualified domain name and port of the machine hosting the Marathon gateway.

  • <tenantID> is the name, or ID, of the tenant.

  • <refreshToken> is the full refresh token returned when you logged in.

Example request

curl -X POST "https://host-ext01.domain.net:9310/v1/auth/token/refresh" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"tenantId\": \"t1616\", \"refreshToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldTOKEN\", \"caller\": \"string\"}"

Example response

{
    "access_token": "JhbGciOiJSUzI1NiIsInR5cCIgOiAiSlTOKEn",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldTOKEN",
    "token_type": "Bearer",
    "id_token": null,
    "not-before-policy": 0,
    "session_state": "ac219f-af37-4bdd-9dc0-5a01a36d8dd6",
    "scope": "profile email"
}

List the workbooks marked for the custom action

Gateway Service: Workspace: /ca/v1/workspace/custom-activity-workbooks/{customActivity}

Use the /ca/v1/workspace/custom-activity-workbooks/{customActivity} API to retrieve the list of all workbooks across the workspaces that are marked for custom action. You can filter the search based on the status (such as Processing) and, optionally, workbook category name. Make note of the desired workspace and workbook IDs defined in the response — these values will be needed later.

Request syntax

curl -X GET "https://<gatewayHost_FQDN>:<port>/ca/v1/workspace/custom-activity-workbooks/<customActivity>?processingStatus=Pending&categoryName=<category>" -H "accept: application/json"

where,

  • <gatewayHost_FQDN> and <port> are the fully qualified domain name and port of the machine hosting the Marathon gateway.

  • <customActivity> is the API name associated with the custom action. This was defined when the API-based custom action was defined in Connect.

    CAUTION: The API name is potentially different than the action name that displays in the workbook detail pane and in the list of workspace features.

  • <category> is optional and is the name of the workbook category to filter by.

Example request

curl -X GET "https://host-ext01.domain.net:9310/ca/v1/case/external-workbooks?processingStatus=Pending&categoryName=EMEA" -H "accept: application/json"

Example response

[
    {
        "id": 4702,
        "name": "WrkBk4",
        "createdBy": "50976124-aaca-4aab-a38f-8acd21e5b351",
        "updatedBy": "",
        "createDate": 1621452610111,
        "updateDate": 1621528473780,
        "description": "",
        "type": "static",
        "policyDetails": {
        "requestedBy": "50976124-aaca-4aab-a38f-8acd21e5b351",
        "requestedDate": 1621528473755,
        "type": "ExternalAction",
        "status": "Pending",
        "externalId": "7890d074-a666-47cd-8bcc-8492f8a2eba2",
        "totalItems": 7119
        },
        "hasSampledResults": false,
        "categoryId": 4701,
        "workspaceId": 4695,
        "workspaceName": "Sensitive Data 4"
    },
    {
        "id": 4684,
        "name": "WrBK2",
        "createdBy": "50976124-aaca-4aab-a38f-8acd21e5b351",
        "updatedBy": "50976124-aaca-4aab-a38f-8acd21e5b351",
        "createDate": 1620773398551,
        "updateDate": 1621009720269,
        "description": "",
        "type": "static",
        "policyDetails": {
        "requestedBy": "50976124-aaca-4aab-a38f-8acd21e5b351",
        "requestedDate": 1620935133455,
        "type": "ExternalAction",
        "status": "Pending",
        "externalId": "c64d9797-f1cc-42ab-899c-1e95d2be7493",
        "totalItems": 7119
        },
        "hasSampledResults": false,
        "categoryId": 4686,
        "workspaceId": 4678,
        "workspaceName": "Sensitive Data 2"
    }
]

 
[
  {
    "id": 147153,
    "name": "collect1",
    "createdBy": "a5c66b75-e043-4c83-ab44-794b0dc43092",
    "updatedBy": "",
    "createDate": 1628675862788,
    "updateDate": 1630620283624,
    "description": "",
    "type": "static",
    "policyDetails": {
      "requestedBy": "a5c66b75-e043-4c83-ab44-794b0dc43092",
      "requestedDate": 1630620283607,
      "type": "CustomActivity-1",
      "status": "Pending",
      "externalId": "71fc21d6-dfbb-462c-b6fb-c6c0c43c3615",
      "totalItems": 1
    },
    "hasSampledResults": false,
    "categoryId": 0,
    "workspaceId": 141179,
    "workspaceName": "Vika WS1"
  }
]

Update the custom action status to Processing

Gateway Service: Workspace Workbook: /ca/v1/workspace/{workspaceId}/workbook/{workbookId}/custom-activity/{customActivity}

After you pick up the data for processing, use the /ca/v1/workspace/{workspaceId}/workbook/{workbookId}/custom-activity/{customActivity} API to change the status of the workbook to Processing. Optionally, you can provide the item success and error count.

TIP: If the processing you are doing external to OpenText Core Data Discovery & Risk Insights takes time to complete, you can repeat the status update as many times as needed to update the success and error counts. This allows the users (workbook reviewers, owners, and so on) to see that progress is being made. The progress bar and counts are updated on the Activity tab of the workbook detail pane.

Request syntax

curl -X PUT "https://<gatewayHost_FQDN>:<port>/ca/v1/workspace/<workspaceID>/workbook/<workbookID>/custom-activity/<customActivity>" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"status\": \"Processing\", \"successCount\": <count>, \"errorCount\": <count>}"

where,

  • <gatewayHost_FQDN> and <port> are the fully qualified domain name and port of the machine hosting the Marathon gateway.

  • <workspaceID> is the ID of the workspace for the workbook with the custom activity. The ID is defined in the response of the request for the list of workbooks with the custom action.

  • <workbookID> is the ID of the workbook with the custom activity. The ID is defined in the response of the request for the list of workbooks with the custom action.

  • <customActivity> is the API name associated with the custom action. This was defined when the API-based custom action was defined in Connect.

    CAUTION: The API name is potentially different than the activity name that displays in the workbook detail pane and in the list of workspace features.

  • <count> is the number of items. Optionally, define the number of items that you successfully processed for the custom activity and the number of items that failed.

    NOTE: The total count defined in the request for success and error cannot exceed the total item count for the workbook.

Example request

curl -X PUT "https://host-ext01.domain.net:9310/ca/v1/workspace/4678/workbook/4684/custom-activity/redact" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"status\": \"Processing\", \"successCount\": 700, \"errorCount\": 19}"

The Processing status is reflected on the workbook list page and on the Activity tab in the workbook detail pane of the workbook.

Retrieve list of documents in the workbook

Gateway Service: Workspace Workbook: /ca/v1/workspace/{workspaceId}/workbook/{workbookId}/documents

Use the /ca/v1/workspace/{workspaceId}/workbook/{workbookId}/documents API to retrieve the documents from a workbook. By default, the documentId, title, and filepath (location of the binary file) fields are returned. Specify additional fields as required, defining multiple fields as a comma separated string. Use the limit parameter to specify number of documents to be returned. If the total number of documents is more than the specified limit, a page token is returned and can be used to get the next set of documents.

For the list of document fields that can be retrieved for custom activities, see Retrievable document fields

Request syntax

curl -X GET "https://<gatewayHost_FQDN>:<port>/ca/v1/workspace/<workspaceId>/workbook/<workbookId>/documents?queryFields=<field>,<field>&limit=<count>" -H "accept: application/json"

where,

  • <gatewayHost_FQDN> and <port> are the fully qualified domain name and port of the machine hosting the Marathon gateway.

  • <workspaceID> is the ID of the workspace for the workbook with the custom activity. The ID is defined in the response of the request for the list of workbooks with the custom action.

  • <workbookID> is the ID of the workbook with the custom activity. The ID is defined in the response of the request for the list of workbooks with the custom action.

  • <field> is optional and is the field name of the additional supported field you want returned. Separate multiple fields with a comma. If you do not want to return fields other than the default documentId, title, and filepath fields, omit queryFields= from your request.

  • <count> is the number of documents to be returned (between 1-1000000; default 1000).

Example request

curl -X GET "https://host-ext01.domain.net:9310/ca/v1/workspace/4670/workbook/4676/documents?queryFields=entities,collection_status&limit=1" -H "accept: application/json"

Example response

{
    "pageToken": "djF8WzE2ODQwODAsIjAwMzM2NGUwOWVkZWQ1ZGZhMTdkZWEzNTFiYTQ5NGUxOWIxNGZmMmYiLDEzMzMzXXwwfHQxNjE2X2l0ZW0tMDAwMDAxfFt7Im5hbWUiOiJ0MTYxNl9pdGVtLTAwMDAwMSIsInNoYXJkQ291bnQiOjUsInNvcnRGaWVsZHMiOlt7Im5hbWUiOiJIQVNIX0xPV1JFUyIsIm9yZGVyIjoiYXNjIn0seyJuYW1lIjoiSEFTSCIsIm9yZGVyIjoiYXNjIn1dfV0=",
    "documentMetadataList": [
        {
        "documentId": 13333,
        "metadata": {
            "collection_status": "CONTENT"
            "entities": [
                {
                    "entityDefinitionName": "entity_details",
                    "score": 0,
                    "properties": {
                        "ENTITY_CATEGORY_ID": "identification_data/names",
                        "ENTITY_ID": [
                            "identification_data/names/all",
                            "identification_data/names/all_cjkvt",
                            "identification_data/names/ch",
                            "identification_data/names/emea"
                        ],
                        "GRAMMAR_ID": "identification_data",
                        "MATCHES": [
                        {
                            "entityDefinitionName": "entity_details_matches",
                            "score": 0,
                            "properties": {
                                "CONTEXT": [
                                    "all",
                                    "all_cjkvt",
                                    "ch",
                                    "emea"
                                ],
                                "SCORE": 0.6,
                                "VALUE": "July ENA"
                            },
                            "highlightFields": {}
                        }
                        ]
                    },
                    "highlightFields": {}
                }
            ],
            "filepath": "//USER-AGENT07/corpData/10k/36A1E4F7-89B5-11E5-9298-005056C00008.eml",
            "title": "EOG for July, Peoples"
            }
        }
    ]
}

Update the custom activity status to Completed

Gateway Service: Workspace Workbook: /ca/v1/workspace/{workspaceId}/workbook/{workbookId}/custom-activity/{customActivity}

Once you have completed processing the data, use the /ca/v1/workspace/{workspaceId}/workbook/{workbookId}/custom-activity/{customActivity} API to change the status of the workbook to Completed if there are no errors, or Completed with Errors if errors were encountered.

Request syntax

curl -X PUT "https://<gatewayHost_FQDN>:<port>/ca/v1/workspace/<workspaceID>/workbook/<workbookID>/custom-activity/<customActivity>" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"status\": \"<updatedStatus>\", \"successCount\": <count>, \"errorCount\": <count>}"

where,

  • <gatewayHost_FQDN> and <port> are the fully qualified domain name and port of the machine hosting the Marathon gateway.

  • <workspaceID> is the ID of the workspace for the workbook with the custom activity. The ID is defined in the response of the request for the list of workbooks with the custom action.

  • <workbookID> is the ID of the workbook with the custom activity. The ID is defined in the response of the request for the list of workbooks with the custom action.

  • <customActivity> is the API name associated with the custom action. This was defined when the API-based custom action was defined in Connect.

    CAUTION: The API name is potentially different than the activity name that displays in the workbook detail pane and in the list of workspace features.

  • <updatedStatus> is the desired completion status, either Completed or CompletedwithErrors.

  • <count> is the number of items. Optionally, define the number of items that you successfully processed for the custom activity and the number of items that failed.

    NOTE: The total count defined in the request for success and error cannot exceed the total item count for the workbook.

Example request when completed without errors

curl -X PUT "https://host-ext01.domain.net:9310/ca/v1/workspacecase/4678/workbook/4684/custom-activity/redact" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"status\": \"Completed\", \"successCount\": 719, \"errorCount\": 0}"

Example request when completed with errors

curl X PUT "https://host-ext01.domain.net:9310/ca/v1/workspace/4703/workbook/4713/custom-activity/redact" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"status\": \"CompletedwithErrors\", \"successCount\": 700, \"errorCount\": 19}"

The Completed or Completed with Errors status is reflected on the workbook list page and on the Activity tab in the workbook detail pane of the workbook.