Contextual Help Links - Bulk Upload Manual

 (This manual was created by Rocket Fuel, an Iridize customer)

  1. Process Overview

  2. Creating/Editing the Spreadsheet

  3. Preliminary Upload

  4. Testing

  5. Troubleshooting

  6. Actual Upload

  7. Download

  8. Hints and Tips

 

  1. Process Overview

Contextual help links appear in the Help Widget as set up with Iridize.

 

Links can be created in two methods:

 

  1. Using the Iridize user interface to build/edit guides which are just links.

  2. Using a bulk upload method that requires loading the links into a spreadsheet and using that Iridize’s import function to load them.

 

This document explains this second method.

  1. Creating/Editing the Spreadsheet

File Format

The Iridize web site accepts any Comma-Separated Values (CSV) file. One can use a standard Excel spreadsheet, and convert to CSV prior to upload.

 

Iridize requires that the first line of the spreadsheet contain the column names. All subsequent lines consist of data.

Columns

The following displays, at the time of this writing, the spreadsheet column names, that must appear in the order shown.

 

But see the note following the list of columns.

original_text

landing_page

lang

translated_text

comment

condition1_code

condition1_summary

condition2_code

condition2_summary

condition3_code

condition3_summary

position

publish

description

api_name

condition1_tags

condition2_tags

condition3_tags

 

Iridize has built some flexibility into the columns. In particular, no conditions are strictly required and also you may add an arbitrary number of conditions as required.

 

When you want to add another condition, add the following column names:

conditionn_code

conditionn_summary

conditionn_tags

 

where n represents the next higher integer after the last that has appeared.

 

Place these columns to follow the existing pattern. For example, if you were to add a fourth condition to the above, add condition4_code and condition4_summary after condition3_code and condition4_summary. Then add condition4_tags after condition3_tags.

Cell contents

Format individual cells as follows.

Column Name

Format

original_text

The default-language label, i.e. the text for the contextual help link the user sees in the DSP.

Example: Learn advanced report techniques.

landing_page

The URL for the contextual help link, i.e. the documentation page in Confluence where the user lands after choosing the link. Note that internally Iridize adds some extra code to the end of the URL for analytics purposes, which you may see if you examine or download links. You do not need to supply this extra data when creating a link, however.

Examples:

When created:

https://wiki.companydomain.com/display/MCRG/Network+Report

 

With Iridize code added: https://wiki.companydomain.com/display/MCRG/Network+Report?utm_source=rocketfuel_dsp&utm_medium=help_widget&utm_campaign=iridize#NetworkReport-Advanced

Lang

This and the next column exist to support localization of the contextual help links.

For the default language, when creating a link leave this column blank.

If you later download the link, Iridize changes this to “--”.

For other languages, supply here language’s two-letter code, e.g. de for German, it for Italian, etc.

Note that each localized link thus has its own row in the spreadsheet.

translated_text

This column and the previous one support localization of the contextual help links.

For the default language, this column should contain the same text as in original_text.

When the lang field has a two-letter value such as fr (French) or jp (Japanese), then enter here the corresponding translation of the original_text column.

 

Note that each localized link thus has its own row in the spreadsheet.

comment

This column is intended for the private use of the link creator and may contain any desired text. The Iridize software preserves whatever you enter. This can have a variety of uses. One useful one may be to ease grouping of the many links. You could enter different values according to the type, creation time or other link attribute and then use Excel to sort on that column.

 

See also the description column below which can also be used in the same way.

conditionN_code

Using Iridize you can control display of contextual help links by applying one or more conditions. A very basic conditional is just to check which screen the user is currently using. Another could be the version of the software the user is using. Or the status of the user themselves.

 

Note that the N in the column name represents the integer which is the number of this condition, starting with 1 and increasing consecutively.

 

This column works with the next column, which contains the actual data to compare.

 

This column specifies the nature of the conditional and can have the following values:

 

CHAR_USER_FIELD

Use this conditional code when you want to compare an environment variable such as a user attribute or installation attribute to a fixed value. The DSP software supplies these values to Iridize. An example of current usage is to check whether a user’s role is managed, i.e. they have the restricted Insights view of the DSP.

 

URL_MATCHING

Use this conditional code to compare against the DSP screen URL. The Iridize software has access to this value and checks it against a fixed value you supply when deciding whether to display each contextual help link.

conditionN_summary

Using Iridize you can control display of contextual help links by applying one or more conditions.

 

Note that the N in the column name represents the integer which is the number of this condition, starting with 1 and increasing consecutively.

 

This column works with the previous column, which contains the actual data to compare.

 

All values in this column must be surrounded by double square brackets, as you can see in the examples below. If you need to actually use a square bracket as a value, contact Iridize to find a usable syntax.

 

This column specifies the values of the conditional, which are specified differently depending on the condition type, as follows:

 

CHAR_USER_FIELD

Use this conditional code when you want to compare an environment variable such as a user attribute or installation attribute to a fixed value.

 

This cell requires four elements. Here is an example:

 

[[has]] [[ui_env]] [[EQ]] [[login]]

 

Read this as “the UI environment variable has a value that is equal to ‘login’”. In real life this is the conditional we use to test whether the user is an external client because they are using https://login.rocketfuel.com and not, for example, https:internal.rocketfuel.com.

 

[[has]]

The first value must be either has or has not. The latter negates the sense of the comparison.

 

[[ui_env]]
The second value is the name of an environment variable that the DSP software passes to the Iridize software. Besides ui_env we also currently use the environment variable role, which is set to managed for our Insights-only users and is not set for other types of users.

 

[[EQ]]

The third value describes the nature of the comparison. Iridize permits other values for this field, which you may investigate at iridize.com if you think you need it, but really this is redundant with the first value and it’s unlikely you will ever need to change this. (The reason it exists, by the way, is that Iridize actually permits other types of conditions to follow a has or has not.)

 

[[login]]

With the final value you specify the actual fixed string that you want compared. If for some reason this needs to contain a bracket, contact Iridize to find out how to handle this special situation.

 

URL_MATCHING

Use this conditional code to compare against the DSP screen URL. The Iridize software has access to this value and checks it against a fixed value you supply when deciding whether to display each contextual help link.

 

This cell must include three elements, for example

 

[[has]] [[/network_report]] [[exactly]]

Read this as “the current screen’s URL, minus the leading and particular text, is ‘/network/report’”.

 

Iridize also supports wildcarding for URL matching. Contact Iridize for details.

 

[[has]]

The first value must be either has or has not. The latter negates the sense of the comparison.

 

[[/network_report]]

Specify the actual URL by stripping out its leading and particular elements. For example, given an actual screen URL of

 

https://www.companydomain.com/companies/4543/campaigns/new

 

remove the leading https://www.companydomain.com and also remove the identifier -- 4543 -- to arrive at a value of

 

/companies/campaigns/new

 

Regarding this removal of identifiers, there can be cases when the identifier is at the end and represents the only element that differentiates the URL from another screen’s URL. In such a case, rather than removing the identifier, change it to the reserved word show.

 

Thus, for example, the URL

 

/companies/dashboard/42

 

would become

 

/companies/dashboard/show

 

[[exactly]]

Possible values for this field are either [[exactly]] or [[]]. Use [[exactly]] if, after removing the leading text and identifiers, the URL must match the string you supply exactly. This could be useful, for example, for distinguishing between /analyze and /analyze/pixels. But use [[]] to indicate that the match need not be exact and in fact that the string you supply can appear anywhere in the URL, This is very useful for URLs such as restrictions. You can specify, for example,

 

/restrictions/browser

 

and then specify an inexact match and by this means match all of the following screens:

 

/subnetwork/restrictions/browser

/companies/restrictions/browser

/campaigns/restrictions/browser

/line_items/restrictions/browser

/line_items/tactics/restrictions/browser

 

Of course this implies that all of these screens’ links go to the same documentation page.

position

The Iridize software supplies a unique integer for each link. When a screen has more than one link, each link’s position value determines its placement in the links menu. The lower the value, the earlier the link appears.

 

When you create a link, leave this cell blank. If you are creating a series of links that are to all appear on the same screen, place them so that the first that should appear is highest in the spreadsheet (i.e is on a lower row number), then the link that is to come next on the screen is next in the spreadsheet, and so on.

publish

This column may have one of two values:1 or 0. A value of 1 -- you may use TRUE if it’s clearer -- means that when you upload the spreadsheet, Iridize makes it live. A value of 0 means that Iridize activates it only for the test environment.

A good practice with this column is to set all links to 0. Then you can upload the spreadsheet and test it. Once you see it is working, you can then upload it a second time, this time simply checking a box that tells Iridize to publish links, even those having a publish value of 0. For more details see Actual Upload (below).

description

This column is for the private use of the link creator and may contain any desired text. The Iridize software preserves whatever you enter. This can have a variety of uses. One useful one may be to ease grouping of the many links. You could enter different values according to the type, creation time or other link attribute and then use Excel to sort on that column.

See also the comment column above which can also be used in the same way.

api_name

When creating a link leave this column blank; it is the Iridize internal identifier of the link and the Iridize software assigns a value to this column should you later download the link.

When you have the value of this column for an existing link, you could use it as kind of a poor man’s link replacement mechanism for just one or a few links. But for details on deleting old links see Actual Upload (below).

conditionN_tags

The Iridize software needs this. The value must always be the keyword widget.

 

Note that the N in the column name represents the integer which is the number of this condition, starting with 1 and increasing consecutively.

  1. Preliminary Upload

You could just upload your spreadsheet and be done, but it’s a safer plan to first test it in the development environment and once you have verified that everything looks okay, go ahead and make it live in the production environment.

 

By the way, there can be about a five-minute delay before your new links become live as Iridize sends them to Amazon’s AWS service. So if you don’t see your links right away, be patient as they may yet appear. Unfortunately there is no notification that the links are ready.

 

Procedure:

  1. When you finish preparing the spreadsheet, navigate to https://iridize.com/account/settings

  2. Scroll down to find EXPORT / IMPORT LINKS:

 

  1. Choose Choose File.

    • Iridize displays a file chooser dialog.

  2. Choose your spreadsheet and Open.

  3. Check the Delete box if you want to remove any existing links.

  4. Do not check the Publish all box.

  5. Choose Import.

    • Iridize begins installation of your links.

 

  1. Testing

  1. Testing is recommended.

 

  1. Troubleshooting

Note that there can be about a five-minute delay before your new links become live as Iridize sends them to Amazon’s AWS service. So if you don’t see your links right away, be patient as they may yet appear. Unfortunately there is no notification that the links are ready.

 

  1. Actual Upload

When you have tested the links and are ready to upload to the live product, the process is nearly the same as described in the Preliminary Upload above. The only change is to now check the Publish all box. Here are the details to make it explicit:

  1. When you finish preparing the spreadsheet, navigate to https://iridize.com/account/settings

  2. Scroll down to find EXPORT / IMPORT LINKS:

 

  1. Choose Choose File.

    • Iridize displays a file chooser dialog.

  2. Choose your spreadsheet and Open.

  3. Check the Delete box if you want to remove any existing links.

  4. Check the Publish all box.

  5. Choose Import.

    • Iridize begins installation of your links.

 

Remember that there can be about a five-minute delay before your new links become live as Iridize sends them to Amazon’s AWS service. So if you don’t see your links right away, be patient as they may yet appear. Unfortunately there is no notification that the links are ready.

  1. Download

You may also download the Iridize link data and save it as a CSV that you can examine using spreadsheet software. This might be useful if, for example your copy is lost or corrupted, or for debugging purposes. (Another way to debug is to use the Guides user interface at iridize.com.)

 

Download procedure:

  1. Navigate to https://iridize.com/account/settings

  2. Login if necessary.

  3. Scroll down to find EXPORT / IMPORT LINKS:

  4. Choose Export.

    • Iridize displays a file chooser dialog.

  5. Choose the file name and location for saving.

 

  1. Hints and Tips

A good way to make a link is to copy and customize an existing one of similar type.

 

One way to copy an entire row is to start at one end, hold down shift and then press the arrow key until reaching the other end. Then copy-paste.

 

Things to check if new links do not appear:

  • Have you given Iridize enough time – about five minutes – to get the links uploaded to AWS?

  • Is the publish column set to 1 (or TRUE) or did you check the Publish All box when importing?

  • If you created your link by copying another one and modifying that, did you leave the api_name column blank for the new one?

If you’re really unable to figure out what has gone wrong you can always go to the Iridize site and check the guides manually. Just search for significant keywords in your label.

 

 

Have more questions? Submit a request

3 Comments

  • 0
    Avatar
    Eyal Lewinsohn

    added export file example.

  • 0
    Avatar
    Pinter, Misti

    What does the following error mean when you are trying to import a file? 

    Error importing links list index out of range

  • 0
    Avatar
    Paul LaBarbera

    I resolved the "Error importing links list index out of range" error. It occurred because my URL_MATCHING conditions did not include [[exactly]] or [[]]. 

Please sign in to leave a comment.