Jump to content
Welcome to our new Citrix community!
  • Combining Citrix ADC and Citrix MicroApps to Access On-Premises API


    cugcblogs

    prestongalwasrnd.png by Preston Galwas, CTA

    Citrix Microapps service launched in 2019 and saw a realization of the value brought by the acquisition of Sapho in late 2018. Microapps help to reduce complexity involved with everyday processes in order to drive productivity gains. If you’re not familiar, it is well worth checking out the overview from Citrix. In this post, we will focus on one of the latest continuous innovations added from the Microapps team to the cloud service – the general availability of the Connector Appliance for connecting to on-premises APIs. This appliance enables the cloud service to facilitate calls to services that live only within your datacenter and thereby allowing your Citrix Workspace to expose Microapps to services that were previously only available from applications within your environment. The implications for this access are far reaching as you can now potentially modernize and optimize common business tasks in order to drive productivity gains in your environment.

    In this post, we will explore deploying the connector appliance, connecting it to your Citrix Workspace, publishing a legacy API via Citrix ADC (formerly NetScaler) in order to enable HTTPS connections, then creating the integration and a Microapp.

    In our demo case, the Windows Application GreenTree is published via Citrix Virtual Apps and Desktops for all users. A common task that was identified in a process review is address changes when employees move house. While this may be accomplished with self-service edits, the business requires this information be validated by HR in order to ensure continuity of pay. Address edits were identified as a target for Microapp. 

     

    Since our Demo API from GreenTree supports HTTP only, on port 9000, we will publish it using HTTPS via Citrix ADC. Load balancing is accomplished in 3 easy steps under Traffic Management:

    galwas070920-01.png.733301adec306ff90c23aec6310d8bbb.png

    Step 1, Add back end server(s)

     

    galwas070920-02.png.6a40b7afa28d4de9f92cf29fb325a04d.png

    Next, create a service group and add the service with the port. In our case, the API listens on port 9000 (non-secure HTTP)

     

    galwas070920-03.png.cc9748fdc5b6805c8cf700ec74dbfae1.png

    Click “No service group members” in the next screen to add members

     

    galwas070920-04.png.52fa335870449c8a527a9d3946a6ed63.png

     

    Find the server in the list and enter the port number, then click OK

     

    galwas070920-05.png.a9114cd5958582396abf44cdc4106a3d.png

    In a production environment, we could also configure a MONITOR, which would allow us to do health monitoring of the back end API. For this demo, we will skip that step (and rely on the default “tcp” port check).

    Create the Vserver and Bind the service group. In this case, we will use NON ADDRESSABLE vserver as we will be using content switching to publish it.

     

    galwas070920-06.png.c0dd712e22a9f990c650eae48c734433.pnggalwas070920-07.png.bfd5fdc468ffdda70dbb6b3ae88b0e1d.png

     

    In a similar fashion to before, we will work from the bottom up under the Traffic Management -> Content Switching

     

    galwas070920-08.png.dd2eec3fcc9b06daec853347dd7e8003.png

     

    Create an action:

    galwas070920-09.png.bb5d06445df1c4fa5e0051b0cbbb886a.png

     

    Then a policy:

     

    galwas070920-10.png.d824777da4454aa97c12d27776fb0aba.png

    Finally, bind the policy to our Content switching vServer (or create one, similar to how the load balancing vserver was created. Give it an IP address, choose ‘SSL’ as protocol, then bind an SSL certificate as well as the policy).

     

    galwas070920-11.png.1e500a52ceff879e71055fc7ddfd060b.png

    Now we can test our API publishing and we see it is working. The URL is determined from the API documentation (including the query string to denote an API key).

     

    galwas070920-12.png.6f016330c7a95ae8bb516400cfaa6b35.png

    Next, we need to deploy a Connector Appliance that can speak to the API. In the log into https://citrix.cloud.com, navigate to “Resource Locations.” While on this page, click “ID,” copy the ID into notepad for later, then click the button for connector appliances.

     

    galwas070920-14.png.048dc5d2f2f45269913f724bdff50b03.pnggalwas070920-13.png.5205d3f8a8c8013718926309666acf8a.pnggalwas070920-15.png.0d634c97af45b87dcacf484231902167.pnggalwas070920-16.png.003cd974fb0ca8313c59b3b7c9440216.png

     

    Once the VM is downloaded to the platform of your choice, boot the device. Configure the IP address info then navigate to the URL shown in the console.  You’ll be presented with an 8-digit code, which you enter into this screen then register. At that point, your connector appliance is ready to chat with your on-prem API. 

    In Citrix Cloud, navigate to Microapps and create a new HTTP integration:

     

    galwas070920-17.png.af03c186e6dd1c2fc65403e8d72604f2.pnggalwas070920-18.png.4701296b85d19ec4c5362796162c9f53.pnggalwas070920-19.png.d3508d31df25007d2b6ed6dc97f88557.png

     

    We need the resource location ID, which can be obtained from the Resource Location’s page (click the “ID” button if you did not retrieve this earlier).  Configure the authentication parameters for your API then save the integration.

    Once the integration is saved, we need to load some data.  For our demo, we will be working with HR information within our demo system.

     

    galwas070920-20.png.d58d1e6a77bfdf807717fd4196596bdf.png

     

    We will fill in the necessary data. Our API requires an API key header or query string, which we can easily add. This will vary depending on your API, so be sure to consult the API documentation. In our case, API calls must include “APIKey”, so we will submit that with all requests to the endpoint /06/HRPerson

    galwas070920-21.png.785482c350e703f50620c998ebc6a31a.png

     

    If we test the service, we see the data return as expected.

     

    galwas070920-22.png.aa58c880bf47060eefd2023cd7a11df1.png

    Next, we fetch the table structure from the API. We see that the result returns a JSON array with HRPersons, so we need to include a JSON pointer to ensure our table selects into the JSON result we’re expecting for our table. Check out an online JSON Pointer tester if you need help with that. I frequently use https://www.jsonpointer.com/.

     

    galwas070920-23.png.e62d4b5de9dabdf9eb692578d446ab68.png

     

    Finally, we will set a primary key on the table that could not be auto generated using the pencil icon.

     

    galwas070920-24.png.47c5bf1119785d8246090667d04fb0ba.png

     

    Once this is saved, a sync will happen and we will head over to the tables page to preview the data. Since we see what we’re expecting we can move on to synchronization.

     

    galwas070920-25.png.e436688f77387801fd6cd0d714105c4c.png

     

    Let’s set up our sync schedule by clicking “…”

     

    galwas070920-27.png.d2bf44c87d88665b26d28b39eaefe34d.pnggalwas070920-26.png.a5c58935127a15ae45efba1c139142d7.png

     

    We’re now able to move on to our Microapp. Click the “…” then choose “Add Microapp” and Navigate to the new, Blank Microapp.

    The first stop is the Properties page for some vital info like name and icon. Don’t forget to hit save at the top of the page before navigating away.

     

    galwas070920-28.png.e54844b16031364f3d445415b476b500.png

     

    Our workflow will call for the ability to search for users in the employee table, then edit them. We will accomplish this with an action that leads to a search page. The search results will then allow you to choose the result and edit the record.

    We will use a FORM page tied to the Employee table. Also, we’ll go back and create a second page called Employee Edit for use later. 

     

    galwas070920-29.png.1efb69eec1e71584b448ae43050e132f.png

     

    For our purposes, we’ll add a Lookup, along with a text input that is hidden. There are multiple ways to pass data to the next details page, but in this implementation we chose using the value from the hidden text input due to issues that arose at the time of writing using the input value directly.

     

    galwas070920-30.png.777284740f377ca198cc0626c01ddf52.png

     

    Once the controls are added, click page details then “Edit Logic”

     

    galwas070920-31.png.9927ba1024dc731c1436e0b9c14c9428.png

     

    The rule here sets the value of the hidden control when the value of the Lookup isn’t empty.

     

    galwas070920-32.png.b41d0f850f1b6876fc1cc09ac8792581.png

     

    Configuring the search button, we add an action to “GO TO PAGE”, and also select conditions for the TARGET PAGE RECORD

     

    galwas070920-33.png.94bcea7cf44612f619e447d4e287ff6a.png

     

    We set the target page record to the employee ID (“code” in our table) to the one that was found using the lookup.

     

    galwas070911-34.png.c4cf1e31aa99b66686096039f8e46eba.png

    Once the lookup, hidden field, and search button are configured, we can flip back over to the Employee Edit page. Using the tools on the left, we can build a nice looking grid for the various properties. Have a play with the different tools available. In our case, we’re only presenting the most relevant fields, not all fields that could be edited. Remember this core principle of Microapps: You’re not trying to re-invent the monolith. Keep it simple, we want the big green “COPY” button on the multi-function printer here.

     

    galwas070920-35.png.3ba907c94e8bd915b99ea134c6aecbbc.png

    When we have this all laid out, we’ll back out and go edit our integration to create a service action. This service action is what we’ll use to save data back to the System of Record (SoR). Go back to the Microapps Dashboard, find the integration, click “…” then “Edit”, then “Service Actions”, and finally “Add Service Action”

     

    galwas070920-36.png.26bf128f4d785fccbd9aeff3e0564f02.png

    This request, much like the GET to populate the Microapps Service cache table, will vary by API. In our case, the API documentation states that there is a POST request to the endpoint /{{CompanyID}}/HRPersons/{{code}}

    We configure the parameters we want to send back to the database (be sure to include any mandatory parameters according to the API documentation)

     

    galwas070920-37.png.b7f4b0b57e075d09eabe3effb4aaeaf4.png

     

    Then we can specify the mandatory bits.  In this case, the endpoint is dynamic according to the URL path (for example, /06/HRPersons/BROWNJ).  To accomplish this, we add a PATH parameter as shown below (remember in our API ‘code’ is the Employee ID)

     

    galwas070920-38.png.6bfc61d8ebd461a4529f8cd6be50f79e.png

    Just like the “GET” request, this particular API still requires we send along the API key as a header or a query string. We will use header.

     

    galwas070920-39.png.db39f119fc773ec0fe13c966cc8e3b69.png

    Next we specify the parameters that will fill the BODY of the POST request.

     

    galwas070920-40.png.4eb889e3bb36b1f539551771c8e15da8.png

    As well as the JSON structure of the body.  Note the syntax of the parameter values as {{VARIABLE}}

     

    galwas070920-41.png.564392b7e8d9a44f1b191a3b6adaf280.png

    {            "HRPerson": {                        "UsualName": {{UsualName}},                        "HRNotes": {{Notes}},                        "IsActive": {{IsActive}},                        "IsSuspended": {{IsSuspended}},                        "StreetAddress": {                                    "Address1": {{Address1}},                                    "Postcode": {{Postcode}},                                    "State": {{Postcode}},                                    "Mobile": {{Mobile}}                                    }            }

    }

    Lastly, for this action we want to immediately re-sync the data so that the users see the data reflected in the Microapps cache rather than waiting for the next sync. 

     

    galwas070920-42.png.76e39f81129269dcb58182b953f7ac3c.png

    We can now save the service action.

    Heading back to our Employee Edit page, the various fields are mapped to the data fields from the table. The save button has an ACTION that executes a service action.

     

    galwas070920-43.png.c001b0889ed15163d49534712a290f68.png

    Chose “Edit parameters” to map the parameters we’ll POST back to the System of Record (SoR)

     

    galwas070920-44.png.ef11598c821af3e9e6beb93852d10c74.png

    Finally, we can now subscribe some users to our Microapp. Back on the dashboard chose “…” for the Microapp then subscriptions. Search for a user or group to add them. 

     

    galwas070920-45.png.523ef808c5490f9c5eba26688ce1c542.png

    With a user or group subscribed, we’re now able to use our Microapp! In Citrix Workspace, we won’t see an action until we’ve used it, so click “View all actions” on the right.

    galwas070920-46.png.acdf9a924a9be7fc9b522e2822e9a135.png

     

    We can search for our user…

     

    galwas070920-47.png.ac8287b78aa89710ee79e65af87983b6.png

     

    View their details, and optionally edit anything and it will be reflected immediately in the system of record (as well as subsequent searches in the Microapp, since we opted to re-sync after our service action).

     

    galwas070920-48.png.fabbecd61a4518631c82f57af6bf99db.png

    If we search for the user again, we see the edit is saved and immediately reflected in both the system of record and the Microapp cache.

     

    galwas070920-51.png.c7ea29e9ab30ea93ba5e3e8ad2008c8b.png

    If we compare this workflow to the published application, we see the steps are greatly simplified.

     

    galwas070920-52.png.bf50a6ae17e1de5e3cec8fc21e14a10c.pnggalwas070920-53.png.d609d3b6e030368081cf7b5e6689aa7e.pnggalwas070920-54.png.d1320d2a7a3365c02887dc91d0536374.pnggalwas070920-55.png.2e618e73b070d1e067aef3af9f6448b9.png

    I hope this walk-through was helpful. Citrix has enabled some truly interesting use cases for businesses to optimize worker productivity and reduce mundane tasks. In our example here, editing an address in the Microapp is likely to save a few minutes every single time as launching the published app, logging in and navigating to the user in the application is a time-intensive task. With work intelligently organized in Citrix Workspace, this routine task becomes a couple of clicks and a quick edit, letting them get on with what it is the need to do. 

    The possibilities don’t end with a simple edit, either. In an upcoming post, we’ll explore how to notify the user that their address change was acted upon so they have confirmation that the change has taken place.

    Until next time.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Create an account or sign in to comment

    You need to be a member in order to leave a comment

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now

×
×
  • Create New...