Latest Contributions by IsmaelChivite

In this blog post I will introduce a handful XLSForm functions that will help you work with user selections on lists.  If you are not familiar with the basics of publishing smart forms in Survey123 using XLSForms, or with selection questions, then I suggest you take a tour of the basic Video Tutorials in our Survey123 YouTube Playlist.  Below you will find a introductory video tutorial on selection questions and lists. Using XLSForm expressions you can process user selections on lists and implement data validation rules, conditional statements to show and hide portions of your forms, and more. Here are some of the most common XLSForm functions you will be able to use: selected(question, value) The selected() function is used to check if a particular choice has been selected from a list. Here is an example: type name label relevant select_one yes_no repair_needed Are repairs needed? text repairs_comment Repairs needed: selected(${repair_needed},'yes') The selected() function returns a boolean value. In the example above, I am using the function within the relevant column, to define if the repairs_comment question will be shown to the end user, or kept hidden. The first  parameter passed to this function is the question on which the user made the selection.  You can only pass questions of type select_one or select_multiple. The second parameter represents your test choice value. It is important to remember that the test choice value represents the name of your choice, not its label.  This makes sense because otherwise, it would be tricky to write expressions in multi-language surveys. Do not pass the label of a choice to the selected() function. The selected() function expects the name value of your choice.  Also keep in mind that this function is case sensitive. 'Yes' is not the same as 'yes'.    The selected() function is particularly useful when working with multiple-choice questions (select_multiple). In the example below, I use the function to populate hidden questions with a value of 1, if a particular choice has been selected, or 0 if not selected.  The violations question is a select_multiple. In it, the end-user can select one or more choices from the violations list. The output of select_multiple questions is a comma separated string representing all the choices selected. That is not very useful if I want to query the data later...   For each type of violation presented in the select_multiple question, I have created a corresponding hidden question. Using a calculation, hidden questions get populated with 1s and 0s based on the user selections. type name label calculation bind:esri:fieldType select_multiple violations violations Violations observed null hidden overwatering Overwatering if(selected(${violations},'10'),1,0) esriFieldTypeInteger hidden brokenpipe Broken Pipe if(selected(${violations},'20'),1,0) esriFieldTypeInteger hidden wrongtime Time if(selected(${violations},'30'),1,0) esriFieldTypeInteger hidden wrongday Day if(selected(${violations},'40'),1,0) esriFieldTypeInteger hidden waterfeature Water Feature if(selected(${violations},'50'),1,0) esriFieldTypeInteger As I indicated before, the output of the selected() function is a boolean. That is, either true or false. In my example, I wanted to store numbers (0 and 1) so I can more easily count values later or use the data in Operations Dashboard. That is achieved by complementing the selected() function with an if() statement. When selected() returns true, signifying that the choice was selected, I store a value of 1 and otherwise a 0. The column bind:esri:fieldType plays an important role here too. For my select_multiple question I chose null. This indicates that the output of the question (the comma separated list of selected values) will not have a corresponding field in the target ArcGIS feature layer.  In other words, a null esri:fieldType says that we are not interested in persisting the output of that question. After all, the values in the hidden questions are really what we want to persist. For the hidden questions, I explicitly set the esri:fieldType to esriFieldTypeInteger, because hidden questions by default are mapped to text fields. Since I know that my calculation is either going to output a 1 or a 0, and I want the output values as numbers, I set the esri:fieldType correspondingly. To learn more about how XLSForm questions get mapped to Esri fields, check the https://community.esri.com/groups/survey123/blog/2015/08/24/xlsform-mappings-to-arcgis-feature-services-an-introduction blog post.    There are some other tempting options for figuring out what choices have been selected in a list. I strongly recommend that you do not get tempted by them: One bad habit is using a straight value comparison on select_one questions: type name label relevant select_one yes_no repair_needed Are repairs needed? text repairs_comment Repairs needed: ${repair_needed}='yes' Technically, it is going to work, but if you get used to that you may be led into this... type name label calculation bind:esri:fieldType select_multiple violations violations Violations observed null hidden overwatering Overwatering if(${violations}='10',1,0) esriFieldTypeInteger hidden brokenpipe Broken Pipe if(${violations}='20',1,0) esriFieldTypeInteger hidden wrongtime Time if(${violations}='30',1,0) esriFieldTypeInteger And that is definitively not going to work!  As you may remember, the output of a select_multiple is a comma separated list of values, so if someone selects more than one option in the violations question, your calculations will not work correctly.  Another temptation, for select_multiple questions, is the use of contains(). For example: type name label calculation bind:esri:fieldType select_multiple violations violations Violations observed null hidden overwatering Overwatering if(contains(${violations},'10'),1,0) esriFieldTypeInteger hidden brokenpipe Broken Pipe if(contains(${violations},'20'),1,0) esriFieldTypeInteger hidden wrongtime Time if(contains(${violations},'30'),1,0) esriFieldTypeInteger The use of contains() could actually work in some cases, but it is not worth the risk. The function selected() works beautifully for both select_multiple and select_one. Use it consistently if you want to check what options were selected in them. count-selected(question) The count-selected() function returns the number of selected choices in a select_multiple question. type name label constraint constraint_message select_multiple toppings toppings Select up to 2 toppings count-selected(${toppings})<3 Pick no more than 2! In this example I built a constraint to prevent people from getting too greedy with pizza toppings. If the number of toppings selected is not below 3, a warning message will appear and the user will not be able to submit data. You can also use count-selected() in a relevant statement, for example to present a comments field if any issues have been found during an inspection. type name label relevant select_multiple comps issues Check manhole components with issues text comments Enter comments relevant for repair effort count-selected(${components})>0 Pretty handy! jr:choice-name(choice, 'question') jr:choice-name() is useful when you need to retrieve the label of a list choice. The syntax goes as follows: jr:choice-name(${activity},'${activity}') In the example above, I am passing with the first parameter the user selection in the 'activity' question.  The second parameter is the question in the form using the list where the choice has been made.  Very often, the first and second parameters will reference the same XLSForm question, but note that the second parameter is enclosed with quotes, because it does not refer to the value (response) of the question, but to the actual question itself. This is a very useful function in several scenarios: When you want to include the label of a selected item in the payload of a webhook. When you want to store the label of a selected item in your target feature layer. When you want to display the selected item's label in a note, or use it within a label (dynamic label). Take this example: type name label calculation select_one priority priority Priority of the incident hidden priority_label Repairs needed: jr:choice-name(${priority},'${priority}') The hidden question, obviously, will not be shown in the form to the user, but will keep the label of the selected choice in the priority question.  This value will be stored in the target feature layer of the survey, and will also be part of the payload sent in any webhooks you configure. If working with multi-language surveys, the jr:choice-name() function will return the label in the language active when the user submits the data.      A common use case for jr:choice-name() is dynamic labels. Dynamic labels are discussed in more detail in the https://community.esri.com/groups/survey123/blog/2018/11/01/understanding-dynamic-labels-in-survey123-for-arcgis blog post. In short, dynamic labels allow you to embed user responses and the result of calculations within labels in your survey. This is a pretty useful technique to help end users navigate along very large surveys for example, because you can bring more context to your questions, using prior responses. type name label calculation select_one priority priority Priority of the incident calculate priori_label Priority Label jr:choice-name(${priority},'${priority}') text comments Describe why the priority is ${priori_label) When using dynamic labels, you cannot include expressions within the label. You can only perform simple variable replacements. This is why in the example below I first add a calculate question to get the label, and then I embed the variable within the label of the comments question.  Just for clarity, the following will not work: type name label select_one priority priority Priority of the incident text comments Describe why the priority is jr:choice-name(${priority},'${priority}') I always wonder why the jr:choice-name has the jr: prefix in front of it. I am sure there is an obscure explanation somewhere for that. I also wonder why if the function was named jr:choice-name instead of choice-label, since the output is the label, and not the name. Oh well... the function works nicely, so I would not dig to much into this mystery of the XLSForm specification. selected-at(question, number)   The selected-at() function is unique to select_multiple questions. It is kind of an exotic function but I am including it for completeness. It returns the choice name selected at a specific index within the selection. This is best explained with pizza:   type name label calculation select_multiple toppings toppings Select your top 3 favorite toppings hidden most_favorite selected-at(${toppings},0)   Above, the selected-at() function is first passed the output of our toppings question. That is, a comma separated list with 3 pizza toppings selected by the user.  The second parameter indicates the zero-based index in that list for which we want to know the value.  Since we are passing 0, the output will be the pizza topping that the user selected in the first place. If we pass an index 2, it will give us the last topping that the user selected, assuming that we have limited the number of favorite toppings to 3. This function is particularly useful when you want to know the exact order in which the user selected choices within a select_multiple question.  If the index you pass in the second parameter is not within the range of the user selection, the function returns an empty string. For example,  selected-at(${toppings},4) will return an empty string if the user only selected 3 items. All XLSForm functions described in this document are compatible with both the Survey123 field app as well as with web forms.    ... View more

[Last updated March 4, 2019]   On November 6, 2018, Esri introduced the concept of User Types in ArcGIS. User Types will be available with the upcoming ArcGIS Online December 2018 update.   ArcGIS User Types are an evolution of the ArcGIS Named User licensing model, bringing more granularity into how capabilities and apps are made available to users.   In this blog post, I want to describe how these upcoming new ArcGIS User Types relate to the different capabilities and components of Survey123 for ArcGIS.   An Overview of ArcGIS User Types   A great resource to learn more about the upcoming ArcGIS User Types is Kelly’s What is coming in ArcGIS Online: Introducing User  Types blog post. I recommend that you read her post as a foundation for the details described here.   ArcGIS User Types define what capabilities and apps are available to ArcGIS users within an organization. The image below describes the different User Types that will be made available in the December release of ArcGIS Online.     From a practical perspective, your existing Level 1 Named Users will become Viewers and your Level 2 Named users will become Creators.  What this means from a Survey123 perspective is that whoever was assigned a Level 2 or Level 1 Named User will continue to be able to do exactly the same things as before. For the existing Named Users you may already have, you can consider the new User Type model as simply a name change. End-user workflows and available functionality will not change.   What is more interesting is that a set of 3 new User Types will now be available for purchase.  This is great news, as these new User Types will give you extra flexibility to add new ArcGIS users into your organization to perform specific tasks with Survey123.   ArcGIS User Types from a Survey123 perspective.   Let’s look in more detail at what each of these new User Types can do with Survey123.   Creator (formerly known as Level 2)   The Creator User Type is designed for those in your organization who create maps and apps for others to use. A Creator User Type (formerly known as Level 2), is what you need if you want to publish new surveys into ArcGIS. A creator, for example, can log into the Survey123 website and use Web Designer to create and publish a new survey. Similarly, creators can download and use Survey123 Connect to publish surveys using the XLSForm specification. Other Survey123 actions that are unique to the Creator User Type include: Uploading new survey report templates, generating batch survey reports or managing survey webhooks.   You will always need at least a Creator User Type (or other User Types above such as GIS Professional) in order to get things going with Survey123.  You need Creators to publish and manage the surveys that people will use in an organization.   With a Creator User Type you can also design dashboards to display data captured from Survey123, or put together Workforce for ArcGIS projects to coordinate Survey123 field work.    Creators also include all the capabilities and apps licensed for the Field Worker, Editor and Viewer user types. Field Worker   This is a new User Type for those in your organization who want to use ArcCGIS mobile apps to perform field work. Field Workers get the Field Apps Bundle, which includes Workforce, Collector and Survey123 for ArcGIS.   The Field Worker User Type is a step down from the Creator User Type in that Field Workers do not have the ability to create new content such as surveys, maps and apps, but includes what is needed to submit surveys from the Survey123 field app. I am particularly excited about the Field Worker User Type because for the longest time many of you have been asking for a more affordable way to equip field crews with a complete suite of mobile GIS apps to do their job. A user type including what a field user needs, but nothing else. That's the Field Worker User Type.   This is the User Type you will want for those who are required to capture data with the Survey123 field app.  Think field crews performing asset inventories or inspections, damage assessments, etc.   Field workers also include all capabilities and apps licensed for the Editor and Viewer User Types. Editor   The Editor User Type is designed for people who need to make simple feature edits (adds, updates, deletes) in ArcGIS.  The Editor User Type does not include the Field Apps Bundle, meaning that Editors cannot use the Survey123 field app, however, Editors can submit surveys from a web browser. The Editor User Type can also be a good choice for people who perform, QA/QC workflows or simple edits from web applications against data captured from Survey123.   If it is your preference, you can complement an Editor User Type with add-on app licenses. That is, you can buy ArcGIS apps a-la-carte and assign the licenses to your existing Editor User Types.  For example, if you feel like your field crews do not need Collector, Workforce and Survey123, instead of purchasing a Field Worker User Type license, you can buy Editor User Types and assign the Survey123 field app to them.   Editors also include all capabilities and apps included in the Viewer User Type. Viewer (formerly known as Level 1)   Viewers, formerly known as Level 1 Named Users, are designed for people who need to look, but not update, information in ArcGIS. Viewers can for example look at real-time dashboards built on top of Survey123 data, use web apps built with Web AppBuilder to visualize information.  The Viewer User Type also grants read-only access into the Survey123 website. That is, Viewers can look at the Overview, Data and Analyze pages of surveys to inspect the results of surveys.    Features in the Survey123 website that require permissions to create content, such as publishing new surveys, export reports in batch or configuring web hooks, will not be available to Viewers. Again, Viewers just can look at data.   GIS Professional   The GIS Professional User Type sits above all the User Types I described so far. It includes everything in Creator plus a license to use ArcGIS Pro.  I list GIS Professional last because it does not add any specific Survey123 capabilities that would be missing in Creator. Adding GIS Professionals into the mix for your Survey123 deployments could be of interest when you plan to further process or analyze data captured with Survey123 for example.   Using Survey123 without an ArcGIS Account   For completeness, I would also add that any person, even without an ArcGIS account,  can submit data using the Survey123 field and web apps if the survey has been shared  publicly. The new User Types bring no changes to public surveys.   Other important facts   To add more clarity to the different User Types and what you can do in Survey123, here is a summary of what each User Type can do.  IsmaelChivite_0-1644547236284.png   Please note that through the use of ArcGIS Roles, administrators define the specific privileges that a particular ArcGIS member has access to. ArcGIS Roles can be used to restrict privileges initially included with a User Type and described in the table above. For example, if a user  with a Creator User Type is assigned a User role (which revokes privileges to publish feature layers), then that user will not be able to perform the operations above that are unique to the Creator User Type. Similarly, if a user with a Field Worker User Type is assigned a Viewer role, then its  privileges will be similar to that of a Viewer User Type.   Once a User Type is assigned, can it be changed? Certainly. As an ArcGIS Administrator you can switch User Types. For example, a person can be initially assigned an Editor role to submit surveys over the web and eventually be upgraded to a Field Worker to also be able to use the Survey123 Field app. Conversely, a Creator can be demoted to a Field Editor, Editor or Viewer. Now, in that case, you will want  to make sure any items owned by the Creator are  transferred to some other user with a Creator User Type, so the maps, surveys and other items can be maintained.   A user granted a particular User Type can also be granted access to additional apps not originally included with the User Type. For example, a Field Worker user can also be granted a license of Navigator for ArcGIS, and a Creator can be granted access to Insights for ArcGIS or other add-on apps.   What you cannot do is to break apart a User Type. For example,  you cannot take away from a  Field Worker the Survey123 license and give to an Editor.   Will User Types be available in ArcGIS Enterprise? Yes. Starting at version 10.7, which is scheduled for release around March 2019.   What is the price of these User Types? It varies. My suggestion is that you contact an Esri representative. There are programs for personal use, students, non-profit, small and large organizations.   Summary   ArcGIS User Types are simply an evolution of the ArcGIS Named User licensing model.  As a Survey123 user, you should not fear the transition from the existing ArcGIS User Levels we use now, to the new ArcGIS User Types coming in the December 2018 release. Your existing Level 1 and Level 2 users will be automatically transitioned to the Viewer and Creator User Types with absolutely no impact to end users.   The transition of existing Named Users will have minor impact from an ArcGIS administrative perspective: Some minor UX changes as described in this blog post.   New User Types including Editor and Field Workers are of particular interest for the deployment of Survey123 within organizations. They both provide lower entry points to people who need to use the Survey123 field app (Field Workers) or submit surveys over the web (Editors).     Overall, the new User Types include capabilities progressively: The Viewer can view maps and the results of surveys The Editor can do everything a Viewer can do and also submit data through survey123 smart forms in a web browser The field worker is like an Editor but also includes licenses for the Survey123, Collector and Workforce mobile apps Finally, the Creator does everything a Field Worker can do, plus also create new content, including designing and publishing surveys.    Understanding all User Types, will help you maximize your investment in ArcGIS. Carefully choose the number of User Types to add into your organization, based on what people will typically do.  ... View more

A minor update to the Survey123 field app in the Google Play and Amazon stores has just been made available. This new build, addresses BUG-000117493, which affected Android 7.0 (and newer) devices when attempting to connect to an ArcGIS Enterprise portal using non-CA-signed certificates. BUG-000117493 "SSL Handshake failed (6)" error is generated in Survey123 app when attempting to connect from Android 7.0 or higher to an ArcGIS Enterprise portal using non-CA-signed certificate. The new build number for the Survey123 field app on Android is 3.1.159. ... View more