DokuWiki

Site Tools

Trace: • ws_payloads_retrieve_payload
guides:ws_payloads_retrieve_payload

Differences

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

Link to this comparison view

Next revision		Previous revision
guides:ws_payloads_retrieve_payload [2020/08/23 16:44] – created brett.zamoraguides:ws_payloads_retrieve_payload [2020/08/24 21:24] (current) – brett.zamora
Line 1: Line 1:
 ==== payloads:retrieve_payload ==== ==== 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. In it's simplest form, with no parameters supplied, the payload service returns a list of supported repository names and a count of the number of payloads in each repository.+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 12: Line 16:
 {{tablelayout?colwidth="75px,575px"&rowsFixed=1&rowsVisible=10&float=center}} {{tablelayout?colwidth="75px,575px"&rowsFixed=1&rowsVisible=10&float=center}}
 ^ Method ^ URL ^ ^ Method ^ URL ^
-| GET | <nowiki>https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads</nowiki> |+| 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 | 
  
  
Line 40: Line 53:
 **Endpoint:** **Endpoint:**
  
-<nowiki>https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/payloads</nowiki>+<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</color>+<color #7092be>Sample Response (Note: Most of the Base64 image text was removed for readability.)</color>
  
 Status Code: 200 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> <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> </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> </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 
 + 
  
guides/ws_payloads_retrieve_payload.1598201080.txt.gz · Last modified: by brett.zamora