Differences

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

--- guides:ws_payloads_retrieve_payload [2020/08/23 18:06] – 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
@@ Line 95: / Line 100: @@
 {
     "Exception": {
-        "Code": "InvalidUserCredentials",
+        "Code": "PayloadFileLockError",
-        "Message": "Invalid Session Id"
+        "Message": "The payload standard_testagent1-202007140415-00003.1.1_200723151458170.xml not locked."
     }
 }
@@ Line 103: / Line 108: @@
 ----
+**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