BYRD - Administrator’s and Developer’s Guide

Upload and Publish Items

1. Upload a file

Request:

Use REST endpoint to upload a file:

POST /api/v1/gatherings

Set Content-Type:
multipart/form-data

Use form field:
file: <filename> <iostream>

REST endpoint returns JSON list containing each uploaded file. Note that if the uploaded file is an archive (e.g. a ZIP file), each file inside that archive will be listed and also needs to be imported separately!

Response:

[
    {
        "gatheringKey": "<UUID-same-for-all-files>",
        "assetKey": "<UUID-per-file>",
        "path": "<Path-of-file>",
        "contentType": ""
    }
]

2. Import items from an uploaded file

Request:

Start import request PER file:

Use REST endpoint: POST /api/v1/imports

Set Content-Type: application/json

Use the following JSON object as request:

{
    "gatheringKey": "<See-Above>",
    "path": "<See-Above>"
}

Unfortunately, this request will return NO value.

3. Validate items

Request:

Validate items using the following endpoint:

POST /api/v1/validate

Set Content-Type: application/json

Use the following JSON object as request:

{
    "oldItem": {},
    "newItem": {},
    "attributeNames": []
}

To validate newly created items, the oldItem parameter can be removed. To validate an item on all attributes, the attributeNames can be removed, but if provided, the item will be validated based on those selected attributes.

Response:

Sample response on item validation is given below:

{
    "validations": {
        "simple_date": [
            {
                "name": "simple_validation",
                "level": "Warning",
                "path": [
                    "simple_date"
                ],
                "message": "'Simple Date' should not be a Friday",
                "params": {
                    "msg_id": "friday",
                    "err_val": "2013-07-26",
                    "err_val_msg": "'2013-07-26' "
                }
            }
        ]
    },
    "attributeStates": {
    },
    "calculations": {
    }
}

4. Create a selection of items

Request:

Create a selection of items using the following endpoint:

POST /api/v1/selections

Set Content-Type: application/json

Use the following JSON object as request and provide a list of primaryKeys for the items that should be included in the selection:

{
    "primaryKeys": []
}

Response:

Sample response on item validation is given below:

{
    "selectionId": "<UUID>",
    "numberOfItems": 1
}

The response object returns a unique selectionId and the total numberOfItems included in the selection.

5. Publish selected items

Request:

Publish the selected items over a communication channel using the following endpoint:

POST /api/v1/publications

Set Content-Type: application/json

Use the following JSON object as request:

{
    "selectionId": "<See-Above>",
    "destinations": [
        {
            "destinationType": "COMMUNICATION_CHANNEL",
            "destinationId": "<Channel-ID>"
        }
    ]
}

The request requires a selectionId for the items to be published and a list of destinations which contains the communication channels to use for publication. The destinationType can be either IN_PLATFORM or COMMUNICATION_CHANNEL. For IN_PLATFORM type, the organization ID is used as the destinationId while the COMMUNICATION_CHANNEL uses the communication channel ID which can be fetched using the endpoint:

GET /api/v1/communicationchannels

Response:

This request will return NO value.

6. Fetch CIC reviews received on an item

Request:

Retrieve CIC reviews received on an item by a supplier using the following endpoint by providing the item's primaryKey:

GET /api/v1/supplierreviews/<primaryKey>

Response:

[
  {
    "primaryKey": "<primaryKey>",
    "supplierId": "<supplierId>",
    "channelId": "<channelId>",
    "messagingAssetId": 111111111111111,
    "supplier": "supplier",
    "reviewer": "reviewer",
    "reviewStatus": "APPROVED",
    "date": 1624017700422,
    "comment": "",
    "messagingCreatorType": "REVIEW"
  }
]

The corresponding messagingAssetId can then be used to fetch the xml message using the endpoint:

GET /api/v1/messaging/messagingassets/<messagingAssetId>

To view all received messaging assets, the following endpoint can be used:

GET /api/v1/messaging/messagingassets/