How to determine Custom Order Rule Context and Field

[joe.mag]

As always, my apologies if this question has already been answered by documentation or an existing post on the DevForm but I've searched and experimented and am none the wiser for it!

Here's my question: As we know Custom Order Rules involve declaring a function whose name is of the form <Context>_<Field>_<Aspect>. Here's the thing--how can I get a definitive list of all of the possible Contexts and Fields? I've the Visual Studio Object Browser to look at the SoftPro assemblies, I've read the SDK docs, I've searched the forum. I can't seem to find this information anywhere.

Could someone please point me in the right direction?

[BobRichards]

There is no document with this information. From a developer point of view, the Field Code Browser and/or Shell/Server/API package breakpoints are your best way to understand the various objects.

Do you have a specific question?

[joe.mag]

Thanks for the information, Bob. I do have three followups:

1) I'm not 100% clear on how I translate an item from the field code browser to the <Context>_<Field>_<Aspect> specification. Is it always just <parent object>_<field-name>_aspect? What if the parent is a collection--do you drop the "s" on the plural collection name?

2) Apparently 3.0/4.0 handles the naming of published document in a manner that isn't consistent with our internal policies. I would like to copy the document's description over the Select-generated name value and a COR seemed like a reasonable approach. Can you suggest what the function I'll write to do this should be named?

3) I found a reference to using the syntax "args.Context.Root....." within a function to access properties in the object model that are beyond the context of the current function. Are there any limits to this or can I pretty much get to any property that's on any object in the order's object model?

Thanks again

[BobRichards]

1) I'm not 100% clear on how I translate an item from the field code browser to the <Context>_<Field>_<Aspect> specification. Is it always just <parent object>_<field-name>_aspect? What if the parent is a collection--do you drop the "s" on the plural collection name?

Not all objects shown in the Field Code Browser (FCB) represent fields on the UI directly. The best case of this is collections (plural names). The Order.Contacts FCB object represents the collection of all order contacts. As shown in the SDK (How-To --> Custom Order Rules --> Aspects: Value and Validate), you can use a Python for/in statement to access each contact.

2) Apparently 3.0/4.0 handles the naming of published document in a manner that isn't consistent with our internal policies. I would like to copy the document's description over the Select-generated name value and a COR seemed like a reasonable approach. Can you suggest what the function I'll write to do this should be named?

I'll have to research this.

3) I found a reference to using the syntax "args.Context.Root....." within a function to access properties in the object model that are beyond the context of the current function. Are there any limits to this or can I pretty much get to any property that's on any object in the order's object model?

Not all contexts have a Root property. But if it does, this is what the Root property was designed for - a way to get to the top level of the order. You are free to navigate anything in the order. Just make sure there is a Root property! A collection does not have a Root property but an individual item in the collection may.

[Melissa McBerkowitz]

Joe,
One additional note about context - when you have a field highlighted in the field code browser, there's a box on the bottom of the browser that gives you information about the highlighted field. This shows you the context name, which is the text you need for these custom rules (for "<Context>"). The bold field name shown here is the same name you'd use for the <Field> component of the rule.

In addition to Context.Root, many objects have a "Parent" property that gives you access to whatever object owns your rule's context object. For example, a rule on Person could reference the person's Parent contact in this way.

[joe.mag]

Melissa and Bob,

Thanks for the additional information. For most fields that seems like a very useful approach--just click in field and look at the info in the field code browser. However, there are two places where I think this doesn't help:

1) SoftPro screens that use controls other than text boxes. For example, on Order Contacts screen clicking on an item in the grid doesn't show you the collection's name in the FC browser.
2) Fields that are read-only in the user interface don't link to the field code browser (which is actually an inconvenience above and beyond CORs)

Finally, I wanted to go back to collections. I see what Bob means about iterating over the items in a collection but what would the signature of such a function look like? I had thought, based on my COR work with invoices, that the function was named for the individual object, not the collection (e.g. PremiumCalculation_FinalPremium_Value vs. PremiumCalculations_FinalPremium_Value). If you do name it after the collection what would that look like?

Thanks!

[BobRichards]

1) SoftPro screens that use controls other than text boxes. For example, on Order Contacts screen clicking on an item in the grid doesn't show you the collection's name in the FC browser.

If I understand the question, I agree that clicking in the list of contacts does not result in any help from the Field Code Browser (FCB), but if you double-click a contact, then the FCB shows the collection name in the Path at the top of the FCB. Even if every field was read-only, this is a place to start.

2) Fields that are read-only in the user interface don't link to the field code browser (which is actually an inconvenience above and beyond CORs)

I agree. This is a pain for us, also.

Collections

You can access collections like any other item in the FCB. Frequently collection objects don't have a UI representation - just the individual items in the collection. Going back to the Validate example from the SDK (referenced earlier), we hooked the "Order_Contacts_Validate" object. You can see this object in the FCB. Be careful what you do with collections, though. If you want to validate a property for each item in a collection, don't do it in the collections object. Do it in a COR for the individual items. That way, the hot-spotting will take the user directly to the UI field that needs fixing.

[joe.mag]

Following your suggestions I came up with several function definitions to enable me to alter the default name assigned to an attachment:

Code: Select all

def Attachments_Name_Value(args):
	args.Value = "this is a test"

def Order_Attachments_Value(args):
	args.Value = "this is too"

Neither works nor is any error generated when I try to save the order. The "def" line in the script editor is underscored with a blue wavy underline.

Unlike when I've had an error in a script which caused the actual save of the order to fail, these attempts don't seem to interfere with the order saving.

I tried to trigger the event by editing an attachment's name--maybe that's not a good trigger to use?

[BobRichards]

When you entered the rule names and started execution by clicking the Start button, you should have seen a warning displayed: Method signature does not match any known rule definition. This means that the rule does not reference a Context/Field that Select knows about and the rule will never be called.

You cannot access the Attachments from the Order via Custom Order Rules. You may want to check the SDK in "How-To --> Print Pipeline" section for information on ways to modify the target of a print operation.