Differences

This shows you the differences between two versions of the page.

--- guides:ws_payloads_retrieve_payload [2020/08/23 17:58] – brett.zamora
+++ guides:ws_payloads_retrieve_payload [2020/08/24 21:24] (current) – brett.zamora
@@ Line 1: / Line 1: @@
 ==== 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.
 ----
@@ Line 51: / Line 56: @@
-<color #7092be>Sample Response</color>
+<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)
     {
-        "Count": 0,
+        for (int i = 0; i < strFolderFileNames.Length; i++)
-        "RepositoryName": "Send"
+        {
-    },
+            // 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")
     {
-        "Count": 0,
+        tbMessageLine.Text = "Locking remote file " + strFileName;
-        "RepositoryName": "Retrieve"
+    }
-    },
+    else if (strAction == "unlock")
     {
-        "Count": 96,
+        tbMessageLine.Text = "Unlocking remote file " + strFileName;
-        "RepositoryName": "Processed"
+    }
-    },
+    else
     {
-        "Count": 0,
+        tbMessageLine.Text = "";
-        "RepositoryName": "Invalid"
     }
-]
+    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 **
-**OR**
+<code C#>
+private void DownloadRemoteFile(string strRepositoryType, string strFileName, string strLocalFolder)
+{
+    tbMessageLine.Text = "";
-Status Code: 500  (When an error occurs.)
+    RestClient client = null;
+    RestRequest request = null;
+    IRestResponse response = null;
-<code json>
+    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)
 {
-    "Exception": {
+    tbMessageLine.Text = "Deleting remote file " + strFileName;
-        "Code": "InvalidUserCredentials",
-        "Message": "Invalid Session Id"
+    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