DokuWiki

This is an old revision of the document!

payloads:lock_unlock_finalize_payload

The payloads web service is a REST structured service that derives its functionality based on syntax used when calling the web service.

The payloads web service was designed to support multiple concurrent sending and retrieving. As such, some specialty functions must be used when performing send or retrieve actions.

Specifically, when retrieving a payload you must first lock the payload. This prevents other retrieve requests from operating on the same payload.

When sending a payload, the payload is stored in the repository with a .tmp file extension, this prevents CeRTNA's sender process, which filters for .xml files from seeing the .tmp payload file. Once the file is successfully written to the repository, the finalize function is used to rename the .tmp file extension to .xml. Important: You must lock the .tmp file before calling the finalize operation.

The unlock operation is provided simply to cover conditions where a locked file may need to be unlocked.

Purpose: Lock, Unlock, or Finalize (rename) A Payload

Request Endpoint

Method	URL
PATCH	https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/{repository}?operation={operation}

Variables:

Variable	Usage	Description
{repository}	Required	The name of the repository
{payload_name}	Required	The name of the payload

Arguments:

Variable	Usage	Description
{operation}	Required	This argument must be one of the following: lock, unlock, or finalize

Request Body

N/A

Request Headers

Key	Value
access_token	{soft-token}

JSON Request Parameters

N/A

Notes:

Any condition that results in an unsuccessful call to the payloads web service will produce a JSON formatted response with a code and message property populated.

Sample Request (lock)

Endpoint:

https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/retrieve/standard_testagent1-202007140415-00003.1.1_200723151458170.xml?operation=lock

Sample Response

Status Code: 200

{
    "result": "true"
}

OR

Status Code: 500 (When an error occurs.)

{
    "Exception": {
        "Code": "PayloadFileLockError",
        "Message": "The payload standard_testagent1-202007140415-00003.1.1_200723151458170.xml already locked."
    }
}

Sample Request (unlock)

Endpoint:

https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/retrieve/standard_testagent1-202007140415-00003.1.1_200723151458170.xml?operation=unlock

Sample Response

Status Code: 200

{
    "result": "true"
}

OR

Status Code: 500 (When an error occurs.)

{
    "Exception": {
        "Code": "PayloadFileLockError",
        "Message": "The payload standard_testagent1-202007140415-00003.1.1_200723151458170.xml not locked."
    }
}

Sample Request (finalize)

Endpoint:

https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/send/standard_demo-20200823_200823124032567.tmp?operation=finalize

Sample Response

Status Code: 200

{
    "result": "true"
}

OR

Status Code: 500 (When an error occurs.)

{
    "Exception": {
        "Code": "PayloadFileLockError",
        "Message": "The payload standard_demo-20200823_200823120859975.tmp not locked."
    }
}