DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

==== 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:** <color #22b14c>**Lock, Unlock, or Finalize (rename) A Payload**</color>

<color #7092be>Request Endpoint</color>

{{tablelayout?colwidth="75px,575px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Method ^ URL ^
| PATCH | <nowiki>https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/{repository}?operation={operation}</nowiki> |

**Variables:**

{{tablelayout?colwidth="175px,75px,400px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Variable ^ Usage ^ Description ^
| {repository} | Required | The name of the repository |
| {payload_name} | Required | The name of the payload |

**Arguments:**

{{tablelayout?colwidth="100px,75px,475px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Variable ^ Usage ^ Description ^
| {operation} | Required | This argument must be one of the following: lock, unlock, or finalize  |

<color #7092be>Request Body</color>

N/A

<color #7092be>Request Headers</color>

{{tablelayout?colwidth="150px,450px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Key ^ Value ^
| access_token | {soft-token} |

<color #7092be>JSON Request Parameters</color>

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.

<color #7092be>Sample Request (lock)</color>

**Endpoint:**

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

<color #7092be>Sample Response</color>

Status Code: 200

<code json>
{
    "result": "true"
}
</code>

**OR**

Status Code: 500  (When an error occurs.)

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

<color #7092be>Sample Request (unlock)</color>

**Endpoint:**

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

<color #7092be>Sample Response</color>

Status Code: 200

<code json>
{
    "result": "true"
}
</code>

**OR**

Status Code: 500  (When an error occurs.)

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

<color #7092be>Sample Request (finalize)</color>

**Endpoint:**

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

<color #7092be>Sample Response</color>

Status Code: 200

<code json>
{
    "result": "true"
}
</code>

**OR**

Status Code: 500  (When an error occurs.)

<code json>
{
    "Exception": {
        "Code": "PayloadNotExist",
        "Message": "The payload 'standard_demo-20200823_200823124032567.tmp' not exist."
    }
}
</code>

**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 [[guides:ws_payloads_delete_payload|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 snippets that appear below show the usage for all 3 web services. (Lock, Unlock, Finalize)

These snippet of code was derived from the [[guides:web_service_toolbox_project|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 [[guides:web_service_toolbox_project|Web Service Toolbox]] application is documented, on the CeRTNA Wiki, to aid in understanding the code snippets shown below.

**Snippet 1: Lock/Unlock**

<code C#>
private bool LockUnlockRemoteFile(string strRepositoryType, string strFileName, string strAction)
{
    bool rc = false;  //Default

if (strAction == "lock")
    {
        tbMessageLine.Text = "Locking remote file " + strFileName;
    }
    else if (strAction == "unlock")
    {
        tbMessageLine.Text = "Unlocking remote file " + strFileName;
    }
    else
    {
        tbMessageLine.Text = "";
    }

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 web service 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)
    {
        var jsonResult1 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        string token = jsonResult1.access_token;

strURL = null;
        client = null;
        request = null;
        response = null;

strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads/" + strRepositoryType + "/" + strFileName + "?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)
        {
            if (strAction == "lock")
            {
                tbMessageLine.Text = "Remote file " + strFileName + " successfully locked.";
            }
            else if (strAction == "unlock")
            {
                tbMessageLine.Text = "Remote file " + strFileName + " successfully unlocked.";
            }
            else
            {
                tbMessageLine.Text = "";
            }
            rc = true;
        }
        else
        {
            var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
            string strMessage = jsonResult2.Exception.Message;
            tbMessageLine.Clear();
            tbMessageLine.Text = strMessage;
        }
    }
    else
    {
        var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
        tbMessageLine.Text = jsonResult2.ToString();
    }
    return (rc);
}
</code>

**Snippet 2: Finalize**

The following is just a fragment of code that was copied over from the [[guides:ws_payloads_delete_payload|payloads:send_payload]] documentation

<code C#>
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;
}
</code>

**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

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International