Inputs are the parameters users enter when generating a Matik presentation to fetch necessary data and customize a template. Inputs are used within Dynamic Content as filters. The screenshot below shows how inputs appear to end users when generating a presentation.
The appearance of Inputs to end users is customizable.
- Display Name: The name of the Input displayed to the end user
- Description: The description is also displayed to the end user
Inputs can be configured to pre-populate input options that end users can select. The Input Source of an input determines where the input is getting value(s) to pre-populate. For example, in the screenshot above, the "Rep Name" input dropdown has been pre-populated with a list of sales reps. This list was obtained from querying a Salesforce data source added to Matik.
-
Input Sources
- User Input: No preselected values. Users can input any value in the correct formatting type. (See "Current Number of Licenses" input above.)
- List: The values for the input come from a fixed list of values defined when creating or editing the input.
- Query/API: The values in the input are populated via a query or API call.
-
Input Types (Depending on what input source you selected, you can select a type.)
- Date range
- Single date
- Single select dropdown
- Multi-select dropdown
- Boolean
- Text box
- Checkbox
To learn more about inputs, check out this video:
Using Inputs in Dynamic Content
See the Dynamic Content Overview article for a full overview of how to work with Inputs and Dynamic Content.
Inputs are inserted into Dynamic Content typing the syntax &: within your SQL query, followed by the input name. When an input is detected in Dynamic content, it will be displayed in the Included Inputs pane. If the input text is orange, it is an existing input. New inputs yet to be created will be displayed in grey text.
In the example below, we create a very basic piece of Dynamic Content called "Account Name" with an input already created, called "account_name." We did this by entering "&:account_name" into the text box. As a result, the account name will be passed through to the end presentation or content when this piece of Dynamic Content is used.
Inputs can also be inserted into SQL queries, API filters, and spreadsheets (via Dynamic Content) for in-sheet calculations. The same syntax &: + <input name> is used when entering into fields.
Note that inputs used in SQL code are not parsed out with SQL commenting. This means that a commented-out input in your queries will still be required to generate a presentation and can be used for slide looping. For example, the query SELECT
col1 FROM table1 -- WHERE col2 = &:input1 will still require the end user to enter in an input. When executed, the input value entered will be part of the commented code, so the -- WHERE col2 = (input value) clause will not be executed. When commenting out inputs in Matik we recommend removing the &: or adding a space between & and : so that Matik does not require the input to generate a presentation.
There are two ways to create an input within the platform:
- Dynamic Content Page
- Inputs Page
Note that input names cannot contain special characters and spaces (!@#$%^&*() " ") with exception to underscores _
Creating Inputs Through the Inputs Page
You can also create a new input, as well as view all existing inputs, by going to the Inputs page. You can access this page by clicking on the Inputs icon in the navbar. On this page, you can see a library of all the inputs created, how they are configured, and all the dynamic content that uses a particular parameter.
Creating Inputs Through the Dynamic Content Page
Inputs can also be created directly in the Dynamic Content page. Type the input syntax within your SQL query - &: - followed by the new input name. A grey pill will appear above the SQL editor. If the input already exists, then the pill will be orange. If you click on the pill, a popup module will appear that will allow you to configure the input.
Embedded Inputs
Inputs may also use other inputs in their API filters or SQL queries. This is useful for reducing selection options on inputs. For example, imagine a company with 10,000 accounts and 100 sales reps. A sales rep would have to select an account from a drop-down of 10,000 items. However, in the "Account Name" input below, the input query filters on the "rep_name" or sales rep input. When an end user generates a presentation that uses this input, they must first select their name (rep_name) as defined by the "rep_name" input. The selection options available on the "Account Name" input will then be limited to only their accounts.
Input Mapping
Inputs can also be mapped to equivalent values that can be more user friendly. For example, if you are creating Dynamic Content that uses a data source that filters on company_id, you can map company_id to company_name. This will make it so that end users can input a company name field, but company_id will be inputted into your Dynamic Content query. For more on Input Mapping, see this help article.
Input Sync
Input options from Query and API sources are updated whenever an input option is presented in Matik. Depending on the speed of the Query or API call, it may take several moments for an input's values to update. During this time "Syncing inputs" will display next to the input name. If your desired input value is available, you may select it before the sync completes.
User-Based Inputs
Information on the user who was logged into Matik and generated the presentation can also be used as an input. This can be useful for filtering input values to be specific to the currently logged in user or for putting personal information into a presentation. For more on user-based inputs see this article.
Input Options
At the bottom of the input page are several options:
-
Default Value - When a value is selected it will automatically pre-populate the input. End users can still change the value but won't have to select it to generate a presentation. This is good for when an input typically uses the same value for the majority of generations.
- You can select a relative to current day default value by using the "Relative to Generation Date" date field
- (Advanced Option) Use raw input value (without formatting for queries) - See below
- Include NULL values - Matik will, by default, remove null values from inputs lists. Include NULL values includes null values in input lists for end users to select. Matik will display 'No Value' to the end user and insert null into the downstream query or API call to a data source when selected.
- Allow user to override returned value - Enables endusers to enter in any value as an input, even if that value is not in the list of values an input returns.
- Include first row of values - Select this if your data does not have header rows to prevent the first row of data from being excluded from input values
Use raw input value (without formatting for queries)
Matik will automatically add the appropriate formatting and syntax to your input values when inserting them in your dynamic content's queries and API calls. For example, in the following query:
When industry is selected, Matik will insert industry with quotes around the value to make it a string or other data type appropriate formatting.
When Use raw input value (without formatting for queries) is selected, Matik will ignore all formatting and syntax rules and insert the input value into the API call or query text directly. This can enable end-users to insert attributes such as tables, column aliases, and more into queries.
Note: Use with caution, when this option is selected end users will have the ability to alter and manipulate queries or insert values that may be in an incompatible syntax resulting in errors.
Becomes:
Best Practices
The inputs you select in your queries should have end-user-friendly display names so that when they attempt to generate presentations, they understand what they need to input. Strategies to improve usability and reliability include:
- Creating dependent inputs (e.g. contract IDs that update when a company is selected)
- Creating Query or API-based inputs that pull directly from data sources (e.g. select name in Salesforce or list of quarters from a table) rather than self-made lists.
- Using common names instead of table IDs to reduce friction in generating presentations
Comments
0 comments
Please sign in to leave a comment.