WorkSpan Admin Tab - Field Mapping page

Admin

Created July 03, 2023 10:21. Last Updated March 06, 2024 06:55

Table of Contents

1. Configure which fields to send to WorkSpan
1.1. Amazon (AWS) use case fields
1.2. Microsoft Partner Center (MPC) use case fields
1.3. Google use case fields
2. Configure default values for new Referrals
2.1. Define default values from Opportunity fields
2.2. Default Ready For Submit field value
2.3. Use literal constants as default values
2.4. Pull a default value from a static resource
2.5. Multi-currency considerations
3. Manage your own custom fields on the Referral object
4. Considerations for mapping Country and other fields, where picklist API names are different from picklist values

The App configures the integration to work straight out-of-box (OOTB), but you would probably want to revise it.

If the “Default value” column is completely at the bottom of the page. However, you can always roll back to the default config by clicking Restore Defaults at the bottom of the “Field Mapping” page. The page shows all Referral fields except for a few purely technical ones that will have no meaning to you. For each field (middle column), there are up to two configuration options: “Send to WorkSpan” and “Default value”. For some fields, one or both options are locked for editing because you shouldn’t alter their behavior since it will break the integration or the data flow.

All changes made on the “Field Mapping” page are NOT applied retroactively, and there is no configuration versioning. i.e., the new default values will only be applicable for the Referrals created or linked; after that, none of the existing Referral data will change.

As for the “Send to WorkSpan”,—only the current configuration is taken into account every time the integration is triggered. E.g., imagine you have created a Referral XX record at some point when the configuration was not to send Deal Size value to WorkSpan. Hence the value was never sent. Later the configuration was changed to send the field. This means the next time the Referral XX record is updated, the latest value will be sent to WorkSpan.

1. Configure which fields to send to WorkSpan

The “Send to WorkSpan” option is a checkbox that controls whether the field value is sent to WorkSpan in the outbound payloads when a Referral is created or edited. It is also used to decide whether to send data at all after updates: if the edited field is not marked to be sent, then the outbound request won’t even be created.

1.1. Amazon (AWS) use case fields

If you are going to use Amazon (AWS) flows, then some fields must have “Send to WorkSpan” checked, or AWS will not accept the Referral and will throw an error:

AWS Account ID
AWS Delivery Model
AWS Use Case
APN Program
AWS Competitive Tracking
AWS Competitive Tracking (Other)
Customer Country
Customer Postal Code
AWS Expected Monthly Revenue
Industry
Is AWS Marketing Development Funded?
Ready For Submit
Is Opportunity From Marketing Activity?
Marketing Activity Channel
Marketing Activity Use Case
AWS Marketing Salesforce Campaign Name
AWS Procurement Type
Customer Software Value
Customer Software Value Currency

All of these are checked OOTB, so you don’t have to do anything if you didn’t change that. However, partner specific fields are restricted from being unchecked for “Send to WorkSpan” check box.

Apart from Referral fields one additional Partner field is required to use Amazon (AWS) flows which is ‘Partner Type’.

To be in sync with AWS v2 updates, WorkSpan has added new fields as listed below:

Few fields have been disabled to be in compliant with AWS v2 changes. You can continue to co-sell with AWS catering with its latest updates.

For Reports and dashboards, the fields will still be shown but a suffix (deprecated) will be added to them.
For other areas like add/edit referral, referral field mapping, view referral, etc. the deprecated fields will be removed. You cannot view these fields on the referral UI.

The following table gives the fields which are being deprecated:

1.2. Microsoft Partner Center (MPC) use case fields

If you are going to use Microsoft Partner Center (MPC Flows), then some fields must have “Send to WorkSpan” checked, or MPC will not accept the Referral and will throw an error:

Customer DUNS
Customer Street Address
Customer City
Customer Country
Customer Name
Deal Size
Deal Size Currency
Close Date
Customer Contact Email
Customer Contact First Name
Customer Contact Last Name
Customer Contact Phone
Customer Contact Title
Opportunity Owner Email
Opportunity Owner First Name
Opportunity Owner Last Name
Opportunity Owner Phone
Ready For Submit
Help Needed from Microsoft

If you are going to map the Help Needed from Microsoft to another field, then review these considerations (See here).

All of these are checked OOTB, so you don’t have to do anything if you didn’t change that. However, partner-specific fields are restricted from being unchecked for the “Send to WorkSpan” check box.

1.3. Google use case fields

If you are going to use Google Flows, then some fields must have “Send to WorkSpan” checked, or Google will not accept the Referral and will throw an error:

Ready for Submit
Google Engagement Model
Google Account Domain
Google Customer Industry
Has the Customer Requested To Be Contacted?
ISV Solution Connect Deal?
Number Of Employees
Primary Product Of Interest
Submitter Email
Summary Of Opportunity
Google Summary Of Support
Customer City
Customer Contact Email
Customer Contact First Name
Customer Contact Last Name
Customer Contact Details - Primary Phone of the customer contact
Customer Name
Customer Postal Code
Customer State
Customer Street Address
Description

2. Configure default values for new Referrals

The Referral object represents an offer from a company to its partner to collaborate on an Opportunity. Hence, a lot of Referral data is likely to be the same as Opportunity (and its related records’) data. But not necessarily, and an AE should always be able to make a decision about which data to share, which to keep, and which to alter. The “Default value” option works in two ways. It defines either (a) the Opportunity fields from which to pull values or (b) literal constant values to use when creating an Outgoing Referral. Option (a) is also applied when linking a Referral to an Opportunity, while option (b) is not. In all the cases, the values are only provided as default values; AE can edit them before saving the record (except for bulk creation and auto-creation because no distinct user interaction is possible in those cases).

The mapping is only applied at the moment when you Create an Outgoing Referral or Link Referral to an Opportunity in Salesforce. It is NOT applied when a Referral is created from WorkSpan, and it is NOT applied at any other time inside Salesforce. I.e., there is NO ongoing sync between the Opportunity and Referral records provided by code in the package. However, there are Flow Templates in the package that you can use to do something like that. Or you can ignore that and implement something from scratch using standard Salesforce automation tools.

2.1. Define default values from Opportunity fields

The option is configured as a pseudo-formula field using field API Names. It assumes that the value is taken directly from the Opportunity field or one of its related records (Account, Primary Contact, Contract, and Owner; custom relationships are not officially supported, but they will most likely work as well). i.e., if you put in Custom__c, the default value will be taken from Opportunity.Custom__c. If you put in Account.Owner.Custom__c — it’ll traverse the relationships and take the value from Opportunity.Account.Owner.Custom__c.

The standard ContactId field on Opportunity is not a “real” lookup; it’s a helper field that is automatically populated (and can’t be manually updated) with the Id of the Primary Contact if one is selected on the Opportunity in the Contact Roles related list.

Hence, it can’t actually be traversed using standard Salesforce notation like Opportunity.Contact.Custom__c—this won’t work if you try to use it in a formula, in automation, or in a SOQL query. However, for your convenience, we support this notation, and you can use it in the “Default value” to get values from the Primary Contact, as demonstrated by the OOTB configuration for the Customer Contact XX fields:

You need to pass two validation checks in order to save the changed configuration on the “Field Mapping” page:

The “Default value” value should correctly traverse to a field that actually exists. E.g. if you mistype Account. Name, you will get a “Field token not found for AcocuntId” error and won’t be able to save.
If the target Referral field is not of type “Text”, the “Default value” type should match it. E.g., if you pre-populate Close Date with Account. Name you will get a “Type mismatch: DATE and STRING” error and won’t be able to save.

The WSA user who is configuring Field Mappings does NOT need field-level security (FLS) access to the target Referral fields to see them in the list—they will see them all except for a few purely technical ones. They also don’t need FLS access to any object(s) and field(s) which are being traversed in the “Default value” pseudo-formula—it is validated in the system context.

However, the AE user who is creating an Outgoing Referral (or linking an Incoming Referral to an Opportunity; or changing the Opportunity in a way that triggers Referral auto-creation) does need FLS to all the objects, fields, and records which are being traversed in the “Default value” pseudo-formula. If they don’t, the default value will be blank.

E.g., if the “Default value” value for Account Owner Email is Account.Owner.Email, then the AE should have at least Read access to the Account field on the Opportunity object, Owner field on the Account object, Email field on the User object, Read access to Account and User objects altogether, and access to the particular Account and User records involved.

2.2. Default Ready For Submit field value

Ready For Submit is a special technical field. It controls whether the data will be sent from WorkSpan to the partner or to another system. However, it does NOT affect the exchange between Salesforce and your WorkSpan instance: the data is sent to WorkSpan regardless of the field’s value. Also, this (and every other) default value only applies to Referrals created in Salesforce. Referrals created in your WorkSpan instance and synced to Salesforce via the integration are not affected by the default mappings.

OOTB, default Ready For Submit value is ‘No’. It means that the Outgoing Referrals are being created in a kind of ‘draft’ state. Aside from the special partner use cases, it mostly affects bulk creation and auto-creation. In both of the latter cases, if the default Ready For Submit value is “No”, then most field validations will be skipped. However, the user might not be able to edit or submit such Referrals without populating some fields first. Regular Referral creation is mostly not affected: the Referral does create with Ready For Submit = ‘No’, but the user is not allowed to skip most of the field validations anyway.

The only way for the user to change Ready For Submit from ‘No’ to ‘Yes’ is by clicking the Submit Referral button. There is no way to change from ‘Yes’ to ‘No’.

2.3. Use literal constants as default values

Using literals as default values for String-based (Texts, Picklists, Emails, URLs, Phones) and number-based (Number, Currency, Percent) fields on the Field Mappings tab. Same as Opportunity field references, the literal values are used both when creating new Referrals and linking to an existing Opportunity. However, unlike the field references, literal values are NOT applied when linking a Referral to an Opportunity, only when creating a Referral. Literal string values should be enclosed in double-quotes.

You can use any special characters (including more double quotes) inside the enclosing double quotes without escaping anything. The app will just take off the very first and the very last double-quote and treat everything in-between as a literal value. E.g. if you put in “William “Bill” Doe”, then the default value will be William “Bill” Doe. There is also no special treatment for new line symbols, i.e. there is no way to get line breaks in a default value unless you go with pulling a value from a static resource.

If the field is a multi-select picklist, then you can use semicolons (without spaces) inside the double quotes as delimiters for different picklist options. E.g. if you put in “APAC; EMEA” as a default value for the Region picklist, then both APAC and EMEA will be pre-selected.

Literal values can’t be combined with field references on the same field. If literal values are not supported for the particular field type (e.g. Number, Lookup, Date), you will get a validation error “Literal value is unsupported for this field.” when trying to save:

If the target field is a picklist or multi-select picklist, then you need to specify API Names, NOT label values.

Also, only existing picklist values can be used as defaults, otherwise, you’ll get a validation error “No such picklist option:”

Literal number values should be entered as plain text without spaces or any other symbols (except decimal points).

2.4. Pull a default value from a static resource

Using literal constants as default values are limited: you can only have a value no longer than 255 characters, and you can’t use any rich text formatting, not even line breaks. But all of that is possible if you map your literal constant value from a static resource and then reference that resource on the Field Mapping tab.

Prepare a .txt file with your default text in it formatted as plain HTML. E.g. if your file looks like this

then the outcome will look like this

Notice how it doesn’t matter where you put in line breaks unless they are HTML tags.

Go to Setup > Static Resources and click New.

Enter the Name (you are going to use it to reference the file), the optional Description (to make it clear for everybody the purpose of the file), select the file, and, very importantly—change the Cache-Control to ‘Public’. Then click Save.

Go to the Field Mapping tab and reference that static resource by prepending ‘$Resource.’ to the Name that you just gave it, e.g. ‘$Resource.DefaultReferralDescription’.

If you want to update the default value later, then you can substitute the file under the same static resource or upload a new one and reference it instead of the old one.

2.5. Multi-currency considerations

Currency handling is very different between WorkSpan and Salesforce. In WorkSpan, every currency field has its own currency type attached to it. In Salesforce, the currency type is attached to the whole record, and all currency fields on this record will be considered that currency type. In order to account for the possible discrepancies and for the situations when WorkSpan sends you a currency type that is not available in your Salesforce org, there are two special fields on Referral: Deal Size Currency and Forecast Value Currency. They store the currency ISO codes that are sent from WorkSpan and are considered when rendering the Opportunity Referral Data LWC. If you already had multi-currency enabled in your Salesforce org before installing the package, then you don’t need to do anything. However, if you’ve enabled it after, then you should go to the Field Mapping tab and map the two Currency fields to the standard CurrencyISOCode field. This way, the currency of these fields on your Referrals by default will be the same as on the Opportunity they are created from.

If you don’t have multi-currency enabled, then the CurrencyISOCode field doesn’t exist.

If you leave the mapping blank (regardless of multi-currency being enabled or disabled), then by default, the currency will be the same as your company’s Corporate Currency.

If you have multi-currency enabled, and WorkSpan initially sends you a currency code (in one or both of the special currency fields) which is an active currency in your Salesforce org, then the package will write that currency into the standard CurrencyISOCode field on the Referral. If it’s an inactive currency, the package will write the standard company currency. If WorkSpan initially sends you two different currency codes in the special fields, the package will ignore them and will write the standard company currency into the standard CurrencyISOCode field. If WorkSpan later sends another currency for one or both of the special currency fields, it does NOT change the already assigned CurrencyISOCode currency code.

You should consider enabling in your Salesforce org every currency that WorkSpan sends to you. After that, change the currency of the Referral record to match the currency coming from WorkSpan. If you set up currency exchange rates, then the native Salesforce currency conversion will take care of calculating and aggregating monetary data. If, for some reason, you have multiple currencies on the same Referral in WorkSpan, there is absolutely no way to match that in Salesforce to properly report.
See here and here for more details on Salesforce multi-currency management and considerations.

3. Manage your own custom fields on the Referral object

If you have created your own custom field, they all will appear on the “Field Mapping” page and, thus, can be configured to be pre-populated and/or to be sent to WorkSpan (where you can further configure where they should go from the staging table). By default, they are NOT sent and have no default mapping.

4. Considerations for mapping Country and other fields, where picklist API names are different from picklist values

If you are mapping a default value from some existing picklist field to one of the picklist fields on the Referral object (Country, Help Needed from Microsoft, your own custom field), then you need to make sure that the source field’s picklist value API names are exactly the same as the target’s field picklist value API names (picklist value labels don’t matter).

If you are mapping a default value from some existing non-picklist field to one of the picklist fields on the Referral object (Country, Help Needed from Microsoft, your own custom field), then you need to make sure that values that will be entered in this non-picklist field are exactly the same as the target’s field picklist value API names.

If you fail to do so, then instead of a correct value being selected in the Referral field (and then sent to WorkSpan), a new inactive picklist value will be added to the Referral field, and this inactive (and invalid) value will be sent to WorkSpan.

Example.

You shouldn’t map workspan__Country__c to Account.BillingCountry, because of Account.BillingCountry is a text field, and workspan__Country__c expects country two-letter ISO codes as API names.

If you are using the standard Salesforce Country picklists, then map it to Account.BillingCountryCode or Account.ShippingCountryCode. If you are NOT using the standard country picklists, but want to map it to a custom Country picklist field, then make sure this field has two-letter ISO country codes as picklist value API names. If you want to map it to a custom text field, then make sure that the only values that will be entered into this custom text field are two-letter ISO country codes, exactly the same as the API names of the workspan__Country__c picklist values: