DokuWiki

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

Variables:

Arguments:

Request Body

N/A

Request Headers

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": "PayloadNotExist",
        "Message": "The payload 'standard_demo-20200823_200823124032567.tmp' not exist."
    }
}

Comment 1:

Following is a C# / .NET sample code snippet that shows how to call the web services associated with locking, unlocking, and finalizing a payload.

The lock, unlock, and finalize web services are web services that are used as part of the send payload and retrieve payload process flow.

Payloads that are 'Sent' (uploaded) are uploaded as .tmp files and the finalize web service is used to rename the .tmp extension to .xml.

Payloads that are 'Retrieved' must be locked before they can be retrieved. If the retrieval is successful and any validation requirements are satisfied, then the remote payload can be deleted with the payloads:delete_payload web service, otherwise the payload can be unlocked and the callers application will determine the next steps in their flow.

The sample code snippet that appears below shows the usage for all 3 web services. (Lock, Unlock, Finalize)

These snippet of code was derived from the Web Service Toolbox that is available on the CeRTNA Wiki. The sample application is intended for easy to read demonstration purposes and not production quality code. The Web Service Toolbox application is documented, on the CeRTNA Wiki, to aid in understanding the code snippet shown below.

private bool SendFile(string strRepositoryType, string strFileName)
{
    tbMessageLine.Text = "";
 
    bool rc = false;
 
    RestClient client = null;
    RestRequest request = null;
    IRestResponse response = null;
 
    string strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/user/login";
 
    // Password has to be hashed.
    // New convention uses a Salt value from the user record
    // See the Login documentation for more detail
 
    string strSalt = GetSalt(tbUserName.Text);
    string strPassword = tbPassword.Password.ToString();
 
    string strHashedPassword = HashPassword(strPassword, strSalt);
 
    string strParms = "{\n\t\"user_name\" : \"";
    strParms += tbUserName.Text;
    strParms += "\",\n\t\"password\" : \"";
    strParms += strHashedPassword;
    strParms += "\"\n}";
 
    client = new RestClient(strURL);
    request = new RestRequest(Method.POST);
 
    request.AddHeader("Cache-Control", "no-cache");
    request.AddHeader("Content-Type", "application/json");
 
    request.AddParameter("Login", strParms, ParameterType.RequestBody);
    response = client.Execute(request);
 
    if (response.IsSuccessful)
    {
        tbMessageLine.Text = "Sending XML file "+strFileName;
 
        var jsonResult1 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        string token = jsonResult1.access_token;
 
        FileStream fs = new FileStream(strFileName, FileMode.Open, FileAccess.Read);
 
        XmlDocument xmlDoc = new XmlDocument();
 
        xmlDoc.Load(fs);
 
        strURL = null;
        client = null;
        request = null;
        response = null;
 
        strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/" + strRepositoryType;  
 
        client = new RestClient(strURL);
        request = new RestRequest(Method.POST);
 
        request.AddHeader("Cache-Control", "no-cache");
        request.AddHeader("access_token", token);
        request.AddHeader("content-type", "text/plain");
        request.AddParameter("undefined", xmlDoc.InnerXml, ParameterType.RequestBody);
        response = client.Execute(request);
 
        if (response.IsSuccessful)
        {
            var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
            string strRemoteFileName = jsonResult2.result;
 
            // You must finalize the remote file to change the extension from .tmp to .xml
 
            string strAction = "finalize";
 
            strURL = null;
            client = null;
            request = null;
            response = null;
 
            strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/" + strRepositoryType + "/" + strRemoteFileName + "?operation=" + strAction;  
 
            client = new RestClient(strURL);
            request = new RestRequest(Method.PATCH);
 
            request.AddHeader("Cache-Control", "no-cache");
            request.AddHeader("access_token", token);
            response = client.Execute(request);
 
            if (response.IsSuccessful)
            {
                tbMessageLine.Text = "XML file " + strFileName+" successfully sent.";
                rc = true;
            }
            else
            {
                var jsonResult3 = JsonConvert.DeserializeObject<dynamic>(response.Content);
                string strMessage = jsonResult3.Exception.Message;
                tbMessageLine.Text = strMessage;
            }
        }
        else
        {
            var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
            string strMessage = jsonResult2.Exception.Message;
            tbMessageLine.Text = strMessage;
        }
    }
    else
    {
        var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        tbMessageLine.Text = jsonResult2.ToString();
    }
 
    return (rc);
}

Comment 2:

A nice utility for experimenting with web service calls is POSTMAN. You can download a free version of POSTMAN from the following URL: https://www.getpostman.com/apps