Implementing the Activity Log Service Provider Interface

Creates an activity log on a given external activity exposed by the connector.

This REST call is a multi-part HTTP request so as to provide attachments in the same call as the activity log data (identifiers, message text, etc). This is a difference with other connector calls. This kind of HTTP requests is typically used by web applications to upload documents to a server.

A multi-part HTTP request with:

• one part named "request" for the JSON description of the activity log
• one part for each attachment with appropriate headers (content type, attachment file name, etc).

If there are no attachments, the connector will still receive a multi-part HTTP request, but it will only contain a single "request" part.

Here is the kind of structure you should expect for the HTTP request.

POST /${connector_path}/com.bmc.dsm.catalog:createActivityLog HTTP/1.1 
Accept: application/json 
Content-Type: multipart/form-data;boundary=Boundary_2_334226257_1559768924968 
Authorization: Basic YWRtaW46cGFzc3dvcmQ= 
Accept-Encoding: gzip,x-gzip 
MIME-Version: 1.0 
Host: 203.0.113.0:7000 
Connection: keep-alive 
Content-Length: 1469 
 

--Boundary_2_334226257_1559768924968 
Content-Type: application/json 
Content-Disposition: form-data; name="request" 
 
{"connectionInstanceId":"DEV","request":{"text":"Here are the documents.\nThanks!","author":{"loginName":"bernard","fullName":"Bernard Rand","emailAddress":"bernardrand@work.com","ntDomain":null},"visibility":"PUBLIC","activities":[{"id":"DFG234FD4DFQAAA00","displayId":"#98765","type":"Ticket"}]}} 
--Boundary_2_334226257_1559768924968 
Content-Type: text/plain 
Content-Disposition: form-data; filename="example.txt"; name="attachment" 
 
This is a plain text file.
 
--Boundary_2_334226257_1559768924968 
Content-Type: text/plain 
Content-Disposition: form-data; filename="example2.txt"; name="attachment" 
 
This is another plain text file.
 
--Boundary_2_334226257_1559768924968 
Content-Type: text/plain 
Content-Disposition: form-data; filename="example3.txt"; name="attachment" 
 
This is a third plain text file.
 
--Boundary_2_334226257_1559768924968-- 

{
  "connectionInstanceId": "DEV",

  "request": {
    "text": "Here are the documents.\nThanks!",
        // Optional message text (attachments may be sent without it).
    "author": {
        // Details of the author of the activity log.
      "loginName": "bernard",
      "fullName": "Bernard Rand",
      "emailAddress": "bernardrand@work.com",
      "ntDomain": null
    },

    "visibility": "PUBLIC",
        // PUBLIC indicates that the activity log is visible to all who participate in the service request.
        // INTERNAL indicates that the activity log should be hidden from end-users
        //   i.e. the requester, the requestee, their collaborators and approvers.

    "activities": [
        // References to the external activities for which the activity log needs to be created.
        // You will get several such references if many activities are associated with the service request.
      {
        "id": "DFG234FD4DFQAAA00",
        "displayId": "#98765",
        "type": "Ticket"
      }
    ]
  }
}

The HTTP response is a regular one containing JSON data (unlike the request).

It will list the references to the created activity logs in the integration target. BMC Digital Workplace Catalog will store these references in order to avoid duplicates during polling.

{
  "created": true,
  "createdActivityLogs": [
    {
      "id": "AB4F0F2A-C869-46A6-A6B2-DD1DDAAD4B72",
      "activity": {
        "id": "DFG234FD4DFQAAA00",
        "type": "Ticket"
      }
    }
  ]
}

Note that the connector may choose, in some cases, to generate several "activity log" entries in the integration target. This can be useful if the integration target does not support attachments and comments together as single entities. In that case, the connector will return as many references as necessary in the "createdActivityLogs" property.

{
  "created": true,
  "createdActivityLogs": [
    {
      "id": "AB4F0F2A-C869-46A6-A6B2-DD1DDAAD4B72",
      "activity": {
        "id": "DFG234FD4DFQAAA00",
        "type": "Ticket"
      }
    },
    {
      "id": "24A54CAF-5461-4FBF-8450-526B7F961B07",
      "activity": {
        "id": "DFG234FD4DFQAAA00",
        "type": "Ticket"
      }
    },
    {
      "id": "562E1D19-FE76-45E5-999B-4080688DE8AC",
      "activity": {
        "id": "DFG234FD4DFQAAA00",
        "type": "Ticket"
      }
    }
  ]
}

{
  "connectionInstanceId": "DEV",
  "request": {
    "criteriaMap": {
      "3501": {
            // Key of the criterion: the connector will use it to reference the corresponding results in the response
        "serviceRequestDisplayId": "7901",
        "activityId": "DFG234FD4DFQAAA00",
        "activityDisplayId": "#98765",
        "activityType": "Ticket"
      }
    }
  }
}

For each criterion, the connector will list the corresponding activity logs. Associated attachments will be referenced in the same data structure, but their contents will be downloaded by BMC Digital Workplace Catalog in subsequent calls through the com.bmc.dsm.catalog:getContent call.

{
  "response": {
    "results": {
      "3501":
          // Corresponds to the criterion key in the request.
        {
          "id": "9e64ea72-db96-4345-9e0f-10bb5c519802",
              // Identifier of the activity log in the external system.
          "text": "Some external comment #1.",
          "author": {
            "loginName": "Allen"
          },
          "visibility": "PUBLIC",
              // PUBLIC indicates that the activity log is visible to all who participate in the service request.
              // INTERNAL indicates that the activity log should be hidden from end-users
              //   i.e. the requester, the requestee, their collaborators and approvers.
         "activities": [
            {
              "id": "DFG234FD4DFQAAA00",
              "type": "Ticket"
            }
          ],
          "attachments": [
            {
              "uri": "commentAttachments/fa4afbc6-3590-4500-bf79-c56d9bbd779f"
                  // Key of the attachment content through the "com.bmc.dsm.catalog:getContent" call.
            }
          ]
        },
        {
          "id": "e2858b16-61dd-4b7a-9dbc-179a29586180",
          "text": "Some other external comment #2.",
          "author": {
            "loginName": "Allen"
          },
          "visibility": "PUBLIC",
          "activities": [
            {
              "id": "DFG234FD4DFQAAA00",
              "type": "Ticket"
            }
          ],
          "attachments": []
        }
      ]
    }
  }
}