DokuWiki

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

To send a payload to a repository, format the body of the request with the XML data and then call the POST method. When the call completes, the name of the payload formatted with a .tmp file extension will be returned.

Important: This function places the XML that is posted into the specified repository using a .tmp file extension. Once the operation is completed successfully, the finalize function must be called to rename the extension from .tmp to .xml

Purpose: Send A Payload To A Repository.

Request Endpoint

Variables:

Request Body

The payload formatted as an XML document.

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

Endpoint:

https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/send

Sample Response

Status Code: 200

{
"result": "Standard_USER-013-190517122842162-00005.1.1_190723173942045.tmp"
}

OR

Status Code: 500 (When an error occurs.)

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

Comment 1:

Following is a C# / .NET sample code snippet that shows how to call the web services associated with sending a local payload to a remote folder.

This snippet 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