Understanding the Instance_Name setting

04-24-2017 03:01 PM
Esri Frequent Contributor
6 20 8,979

Starting with the 2015 June update (Children's day release), Survey123 for ArcGIS supports the instance_name setting in XLSForms. Technically, this setting defines the form submission name as described here.  This setting, if used correctly, will help field users uniquely identify form submissions. This is particularly useful for people who keeps collected data as drafts for later review before actually submitting them.  It can also get handy if you decide to look back at the history of forms submitted in the Survey123 app sent box.  If you ever configure your survey with an Inbox, then this setting becomes a must-have.

Say for example that folks are performing hydrant inspections in the field using the Survey123 app. Say that field crews like to keep their inspections as drafts, because they want to collect info in the field quickly, but want to complete some information such as the estimate of repair costs later, before submitting the final form.

By using the instance_name setting, the author of the survey can control what information is used to uniquely identify surveys in folders such as Draft, Sent, Inbox or Outbox. For example, in our Hydrant Inspection survey, the drafts box could look something like this:

Note that every entry tells us what is the unique ID of the hydrant.  Now it is easier for people to look into their drafts, find a particular form and update it appropriately.

Note how in the Settings worksheet of the form, the instance_name column was filled with the expression:

concat ("Hydrant ID:", ${HydrantID})

The operator concat simply concatenates the string literal Hydrant: and the value of the question HydrantID.  You can concatenate a couple, three, or really as many strings as you want.

The Instance_Name setting is used in the Drafts folder, but also in the Outbox, Sent and most importantly in the Inbox folder.  The Instance_Name setting is also used to label surveys when you decide to look at your surveys within a folder in a map, rather than as a list.

If the above is not clear, have a look at this  video tutorial .

Esri Regular Contributor
New Contributor III

Hi Ismael

It's interesting to add this functionality to the form title : in your example concat ("Hydrant ID:", "${HydrantID}).

Thus, the title may display the instance name to help who ever collecting the information to remember the current instance without leaving the form or scrolling forward and backward.

This is especially helpful in the case of surveys whith a very large number of instances and in the case of surveys with long repeat fields as discused here Surveys with long repeat fields 

Best regards

Occasional Contributor III

Can this be configured in Survey123 Connect, published without overwriting existing data?

Esri Esteemed Contributor

Yes, altering the instance_name does not trigger a republishing of the Feature Service.

New Contributor

Can i, or how can i, use the label of a name field out of the choices tab? 

Occasional Contributor III

Unfortunately you can't right now.  I have gotten around this using a the pulldata() command to look up the label value using the name value that is stored for the field.

Occasional Contributor III

I have gotten around this using a the pulldata() command to look up the label value using the name value that is stored for the field.

Good call, but I can't find a workaround for showing a description for an attribute with coded domain associated when you download data through Inbox.

Any solution? It's quite annoying to see Esri doesn't want to take advantage of domain, a foundation for every geodatabase design.



New Contributor III

It is possible to use different colors in the Instance name listing, to help users spot faster sent items that corresponds best to a new survey to create

Occasional Contributor III

I have a calculated date: now() +30*24*60*60*1000 and I'd like to see this date as my instance_name, in the inbox, but it's showing as a number: 1562828400000. How can I get the date to show?

Esri Esteemed Contributor

Hi Michelle,

To get a text rendering of a date, you need to use the format-date function.  For more details, refer to the 'Date Formatting' section of Formulas—Survey123 for ArcGIS | ArcGIS  and the 'Formatting Dates' section of https://community.esri.com/groups/survey123/blog/2016/04/17/dates-and-time-in-survey123-for-arcgis . 

Occasional Contributor

Is there any way to manipulate the label container in the map to show all the fields instead of truncating them with ...? Thanks, cob

Esri Frequent Contributor

Hi Charles Bailey‌. It is not possible to manipulate the label container in the map.

Occasional Contributor III

I love the idea of color-coding the instance name like inspections that have a due date of 1 week could be orange and a past due date could be red. Did you hear anything back on this?

Esri Frequent Contributor

Hi Michelle Williams‌   Yes. That's possible. Use conditional HTML formatting as shown in the example below

if(selected(${previous_inspection},"Needs_Repair"),concat("Asset ID: ", "<font color='red'>", ${assetid},"</font"),concat("Asset ID: ", "<font color='blue'>", ${assetid},"</font"))

And here is an example of what I got:  Asset 6679 is blue and 770 is red.

Your conditional statement using dates will be different, but the technique would be similar. Of course, you can make the whole Instance_Name with the color that you want.

You can even add emojis. As shown below.

if(selected(${previous_assessment},"Needs_Repair"),concat("Asset ID: ", "<font color='red'>", ${assetid},"</font"),concat("Asset ID: ", "<font color='blue'>", ${assetid},"</font"))

Pretty cool!

Occasional Contributor III

That's perfect!!!! Thank you Ismael.

Occasional Contributor III

The idea was perfect; my execution was not, may I get your help with my code?

This code works: 

concat("WO:",${WO},", UCC:",${UCCReleaseNO}, ", ", ${InsStatus}, ", Proposed Repair Due:" ,format-date(${Prop_Repair_Correction_Date}, '%m-%d'))

Now I need to get the above date to change color respecting the due date. I've tried many iterations of date and I've hit a wall.

if(selected(${Prop_Repair_Correction_Date },"today+14"),concat("Due: ", "<font color='orange'>", ${Prop_Repair_Correction_Date},"</font"),concat("Due: ", "<font color='Black'>", ${Prop_Repair_Correction_Date},"</font"))

Then I need to merge the two.

Thanks in advance, I will use this code for all my future surveys.

Esri Esteemed Contributor

Hi Michelle,

You need to have some comparisons based on the difference between the current day and the due date.  Here's a quick example based on your requirements (substitute the text you want to change color where you see ${example} and the field with the due date for ${duedate} 😞

concat(if(${duedate} - today() < 0, '<font color="red">', if(${duedate} - today() < 7*24*3600*1000, '<font color="orange">', '<font color="black">')), ${example}, "</font>")

Occasional Contributor III

Thank you, James, that was perfect!!! 

Occasional Contributor III

James Tedrick

This is also an issue for me.  Its seems using calculations fail because instance_name errors (doesn't return anything so you cant use a function) when using any function with the inbox.  For instance, jr:choice does not work in the inbox.  Huge limitation with no work around??

Hi , 

I have followed the instructions above and couldn't make it happen.

I need to color the cards by completion status, so i used this line in "instance_name"

if(selected(${CARD_STAT},"3"),concat(${BLDG_ID},"\n", "<font color='green'>Card Completed</font>"),concat(${BLDG_ID},"\n", "<font color='blue'>Card in Work</font>"))

but the results was the html tags itself .

what am i doing wrong ?