top of page
Search

Making sense of the Onshape Configuration String

Writer's picture: Caden ArmstrongCaden Armstrong

Onshape's configurations are one of its best features. Easy to use, well integrated, and very powerful. But when making an Onshape integrated application, they can add a bit of complexity, and are a typical blocking point for newer API developers. But never fear, its really not that difficult.


This configuration string is really only visible to the user in one place: the copy link button. Nestled between the branch name and folder name is the button to copy the current document at this tab button.

If you look at the URL generated by this button, you can see the current configuration. It typically looks something like:


List_AT68kUtZxoHFJ3%3DDefault%3BList_kxFgN7VgGBeRqB%3DDefault%3Blength%3D0.001%2Bmeter


So what does it all means? Well, the first thing to do is unencode the string. Parameters inside a URL cannot have certain characters (such as =) and need to be replaced with a code. The %3D sequence is an encoded equal sign. Putting this into a URL Decode tool, we get: List_AT68kUtZxoHFJ3=Default;List_kxFgN7VgGBeRqB=Default;length=0.001+meter The configuration string is really just a semi-colon separated list of configuration property names and their values.


But what configuration value is List_AT68kUtZxoHFJ3? I don't remember naming anything that. Onshape generates random identifiers for each configuration table to uniquely identify them, as a user might change the names of their tables, or even name them all the same thing. You can see these unique IDs by clicking the "..." in the top right of each configuration parameter. If you really want to, you can even change these to something more literal or easier to understand in your code.



So how do I construct a configuration string? Its quite simple, for each configuration parameter, set the name=value; Ensuring each property is separated by a semi colon. If I wanted to change the above parameter to "small" I have to use the internal value "smal". List_AT68kUtZxoHFJ3=smal;

If parameters are left out of the configuration string, the default value is chosen by Onshape.


"But why isn't my configuration string working?"


When it comes to using the configuration string in API calls, the three main mistakes are: 1. Not encoding the configuration string in URL parameters

If the configuration is in the URL, it needs to be encoded, just as we saw earlier with the %3D encoded =


2. Encoding the configuration in the body

If the configuration parameter is in the body of a post request, this does not need to be URL encoded. Just leave it as is with all the semi colons and equal signs.


3. Units

Onshape really cares about units, and that's a good thing. But it does mean that any configuration parameter that is a length needs to have units. My above example has length=0.001+meter. The units can be changed, but they must be included.


42 views0 comments

Recent Posts

See All

The Hidden Parameter in newSketch

I accumulate a lot of weird and niche knowledge about Onshape and FeatureScript in the course of my work. This is no exception. Honestly,...

Comments


bottom of page