==== payloads:retrieve_payload ====

The payloads web service is a REST structured service that derives its functionality based on syntax used when calling the web service. To retrieve a payload from a repository, call the payloads web service with a repository name and the payload file name.

The payload will be returned in the body of the response as a UTF-8 encoded XML string.

**Important:** The payload must be locked prior to retrieving it.

----

**Purpose:** <color #22b14c>**Retrieve A Payload From A Repository.**</color>


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

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



<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</color>

**Endpoint:**

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


<color #7092be>Sample Response (Note: Most of the Base64 image text was removed for readability.)</color>

Status Code: 200


<code xml>
<?xml version="1.0" encoding="utf-8"?>
<RESPONSE_GROUP PRIAVersionIdentifier="2.4.2">
    <REQUESTING_PARTY _Name="TEST SUBMITTER 1" _StreetAddress="1001 APEX Submission Ave." _StreetAddress2="" _City="Sub City" _State="CA" _PostalCode="91234" _Identifier="35" />
    <SUBMITTING_PARTY LoginAccountIdentifier="bzsub1" _Name="AGENT - TEST AGENT 1" />
    <RESPONSE ResponseDateTime="2020-07-23T14:50:24">
        <KEY _Name="Comment" _Value="Sample comment" />
        <RESPONSE_DATA>
            <PRIA_RESPONSE _RelatedDocumentsIndicator="true">
                <PACKAGE CountyFIPSCode="901" StateFIPSCode="06" SecurityType="1" Priority="Standard">
                    <PRIA_DOCUMENT _Code="Deed" DocumentSequenceIdentifier="1" _UniqueIdentifier="ABC-123" RequestChecksumAlgorithm="SHA384" RequestChecksumValue="0C7580F7-7E3A-4615-A495-55EB66E299A6" ResponseChecksumAlgorithm="SHA384" ResponseChecksumValue="94BE9B16-F97B-4525-BD00-D331F1E7C517">
                        <GRANTOR _FirstName="John" _LastName="Doe" NonPersonEntityIndicator="true" />
                        <GRANTEE _FirstName="Jane" _LastName="Doe" NonPersonEntityIndicator="true" />
                        <RECORDABLE_DOCUMENT>
                            <_ASSOCIATED_DOCUMENT _InstrumentNumber="2009003899200" _RecordingDate="2009-02-25" />
                        </RECORDABLE_DOCUMENT>
                        <EMBEDDED_FILE _PagesCount="3">
                            <DOCUMENT>SUkqAA7qAAAtVZDKI+R4jhkhyPkfI6I6I4hfI4EGAXI4y4UuyODkcUjg5HA+LkR4uKXyOyOFI4YORcyPl2YiOBgjxHZeL5HIuyPnGR4ui6I6I</DOCUMENT>
                        </EMBEDDED_FILE>
                        <STATUS _Code="Rejected">
                            <RECORDING_ERROR _Code="99999" _Description="This is a automatic rejection test message." _OfficersName="John Doe" />
                        </STATUS>
                    </PRIA_DOCUMENT>
                </PACKAGE>
                <RECORDING_TRANSACTION_IDENTIFIER _Value="TESTAGENT1-202007140415-00003.1.1" SecondaryValue="3453453453" />
            </PRIA_RESPONSE>
        </RESPONSE_DATA>
    </RESPONSE>
</RESPONSE_GROUP>
</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>


----


**Comment 1:**

Following is a C# / .NET sample code snippet that shows how to call the web services associated with retrieve a payload from a remote folder/repository and saving it in a local folder.

This snippet 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 snippet shown below.

The general process flow for retrieving a payload from a remote folder is:

  * Lock the remote payload.
  * Retrieve the remote payload.
  * Validate your retrieved payload.
  * If the validation is successful: Delete the locked remote payload.
  * Otherwise: Unlock the remote payload. (Troubleshoot or re-retrieve.)


The following snippets show the process, minus the validation, step...


** Snippet 1: **

<code C#>
private void btnRetrieve_Click(object sender, RoutedEventArgs e)
{
    bool rc;

    string strLocalFolder = tbLocalFolderName.Text;
    string strRepository = (cbRepository.SelectedItem as ComboBoxItem).Content as string;
    
    // See payloads:get_repository_file_names web servicefor the following
    
    string[] strFolderFileNames = getRepositoryFileNames(strRepository);

    if (strFolderFileNames != null)
    {
        for (int i = 0; i < strFolderFileNames.Length; i++)
        {
            // Lock the payload
            rc = LockUnlockRemoteFile(strRepository, strFolderFileNames[i], "lock");
            // Retrieve the payload
            DownloadRemoteFile(strRepository, strFolderFileNames[i], strLocalFolder);
            // Delete the remote payload
            rc = DeleteRemoteFile(strRepository, strFolderFileNames[i]);
        }
    }
}
</code>


** Snippet 2: Lock The Payload **

<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 3: Retrieve The Payload **

<code C#>
private void DownloadRemoteFile(string strRepositoryType, string strFileName, string strLocalFolder)
{
    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;  

        client = new RestClient(strURL);
        request = new RestRequest(Method.GET);

        request.AddHeader("Cache-Control", "no-cache");
        request.AddHeader("access_token", token);
        request.AddHeader("Content-Type", "text/plain");
        response = client.Execute(request);

        if (response.IsSuccessful)
        {
            // Note: Do not try to use the LoadXml API as it does not account for the encoding preamble.
            
            XmlReader myXmlReader = XmlReader.Create(new MemoryStream(Encoding.UTF8.GetBytes(response.Content)));
            XmlDocument xmlDoc = new XmlDocument();
            xmlDoc.Load(myXmlReader);
            xmlDoc.Save(strLocalFolder + "\\" + strFileName);
        }
        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();
    }
}
</code>

** Snippet 4: Delete The Remote Payload **

<code C#>
private bool DeleteRemoteFile(string strRepositoryType, string strFileName)
{
    tbMessageLine.Text = "Deleting remote file " + strFileName;

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

        client = new RestClient(strURL);
        request = new RestRequest(Method.DELETE);

        request.AddHeader("Cache-Control", "no-cache");
        request.AddHeader("access_token", token);
        response = client.Execute(request);

        if (response.IsSuccessful)
        {
            tbMessageLine.Text = "Remote file " + strFileName + " successfully retrieved. Remote file deleted.";
            rc = true;
        }
        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);
}
</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