Job-creation made simple

Let’s say you want to do email notification on lifecycle change in Vault. Here is how the email might look like: powerJobs email In order to achieve this, you want to extend the Vault JobProcessor with an email job. Have you ever tried to create a custom job for your Vault JobProcessor using the Vault API? Here is a short list of tasks you have to do:

  • Install the Vault SDK (software Development Kit)
  • start Visual Studio and create a DLL-Project
  • reference the Vault API assemblies from the SDK
  • Extend your class with the according JobProcessor interface
  • Implement the interface functions
  • Start writing your code (expects coding skills and familiarity with Vault API)
  • copy the DLL bundle into the Extension folder
  • configure the config file in order to inform the JobProcessor about the new job

The tasks above are not familiar to you? Oh, you are not a developer? But you want to do more with your JobProcessor, right? Well, you are not alone! Now, let’s have a look how this works with powerJobs:

  • create a file with the extension .ps1 in the powerJobs\Jobs folder
  • start coding using a much simpler scripting language

Can you see the difference? All right, if you are still with me, then let’s do a practical example. Your interest might be around PDF creation from your CAD files. There is a standard job for this coming with powerJobs, and there are tons of ways to tailor it. But for the purpose of this blog post, let’s see how to create email notifications with powerJobs.

This way we get notified by the JobProcessor, every time a file gets either released, rejected, reviewed, etc. And here is how it works:

Start by creating a new file with the extension .PS1 in the powerJobs\Jobs folder. The easiest way to get there is to double click on the “powerJobs configuration” shortcut on your desktop. Let’s call the file sendEmail.ps1. Just pay attention when you create the file that the extension is really ps1 and not .ps1.txt or similar. You may also see that the symbol for your new file is identical to the one of the other PS1- files in the same folder. Edit the file with any text-editor. Well, it’s better to use either the Windows PowerShell-ISE (Integrated Scripting Environment) or download free editors such as powerGUI or PowerShell Plus. This is the content of the script we are looking for:

$file = PrepareEnvironmentForFile #get the file object of the processed file

#region collect information on lifecycle transition
$lfcTransId = $powerJobs.Job.Params["LifeCycleTransitionId"] #get the lifecycle trasition ID for the lifecycle transition the job has been triggered for
$lfcStateTransition = $vault.LifeCycleService.GetLifeCycleStateTransitionsByIds(@($lfcTransId)) #get the lifecycle trasition definition for the lifecycle transition the job has been triggered for
$lfcStateTransition[0].FromID
$lfcStates = $vault.LifeCycleService.GetLifeCycleStatesByIds(@($lfcStateTransition[0].FromID,$lfcStateTransition[0].ToID))
$fromState = $lfcStates[0]
$toState = $lfcStates[1]
Add-Log -Text "file $($file.Name) transiting from '$($fromState.DispName)' to '$($toState.DispName)'"
#endregion

#region collect information about the involved users
$allUsers = $vault.AdminService.GetAllUsers()
$user = $allUsers | Where-Object { $_.Name -eq $file.Originator }
$causer = $allUsers | Where-Object { $_.Name -eq $file."Created By" }
Add-Log -Text "file orginated by $($user.Name) and last modified by $($cause.Name)"
#endregion

#region build hyperlink to Vault file
$serverUrl = New-Object  System.uri($vault.AdminService.Url)
$filePath = $file."Full Path"
$filePathUrl = $filePath.Replace("$","%24").Replace("/","%2f").Replace(" ","+")
$fileUrl = $serverUrl.Scheme+"://"+$serverUrl.Host+ "/AutodeskDM/Services/EntityDataCommandRequest.aspx?Vault=Vault&ObjectId=$($filePathUrl)&ObjectType=File&Command=Select"
Add-Log -Text "hyperlink: $fileUrl"
#endregion

[System.io.file]::WriteAllBytes("c:\Temp\image.bmp",$file.Thumbnail.Image) #save the file Thumbnail as picture so that it can be attached to the email

#region prepare and send the email
$emailSubject = "The file $($file.Name) trasitioned from '$($fromState.DispName)' to '$($toState.DispName)'"
$emailFrom = "aficio@coolorange.com"
$emailTo = $user.Email # "marco.mirandola@coolorange.com"
$emailBody  = "
Dear $($user.FirstName), the file <b>$($file.Name)</b> transitined to state <b>$($toState.DispName)</b>, as <b>$($causer.FirstName)</b> changed the state.

<img src="cid:image.bmp" alt="" />
<a href="$fileUrl">$($filePath)</a>

If you like to contact $($causer.FirstName) for further explaination, send him an via at $($causer.Email)

sincerely, your humble powerJobs servant
"
Add-Log -Text "Sending email to $emailTo, from $emailFrom, with Subject $emailSubject"
Send-MailMessage -From $emailFrom -To $emailTo -Subject $emailSubject -Body $emailBody -BodyAsHtml -Attachments @("c:\Temp\image.bmp") -SmtpServer "10.0.0.26"
#endregion

Add-Log -Text "Job completed"

Now, the really interesting line is #36, where the Send-MailMessage commandlet is called with simple parameters, that even non-developers can easily understand. The variables above (all starting with $) should also be quite clear. In order to send a message with some individual Vault-related content, such as file information or information around the lifecycle transition etc., we have to “talk” with the Vault server and gather some more details.

Now, the good news is that for certain typical activities, powerJobs provides simple to use commandlets. Here an example: we want to know the file name, who performed the last change and know in which folder the file is located. If we would do it with the Vault API, then the tasks would be:

  • getting the properties definitions
  • getting the properties for the given file
  • getting the folder where the file resides

This would be about 5 to 10 lines of code. With powerJobs, the $file variable, set at the top of the script file, already contains all system and user defined properties and also information about folder location. So, one line does it all for you. Quite handy, huh?

As we like to provide some good information in the email, we have to identify the lifecycle transition we are in. As powerJobs does not yet provide simple commandlets for this task, we will use the Vault API.  These are the lines:

#region collect information on lifecycle transition $lfcTransId = $powerJobs.Job.Params["LifeCycleTransitionId"] #get the lifecycle trasition ID for the lifecycle transition the job has been triggered for $lfcStateTransition = $vault.LifeCycleService.GetLifeCycleStateTransitionsByIds(@($lfcTransId)) #get the lifecycle trasition definition for the lifecycle transition the job has been triggered for $lfcStateTransition[0].FromID $lfcStates = $vault.LifeCycleService.GetLifeCycleStatesByIds(@($lfcStateTransition[0].FromID,$lfcStateTransition[0].ToID)) $fromState = $lfcStates[0] $toState = $lfcStates[1] Add-Log -Text "file $($file.Name) transiting from '$($fromState.DispName)' to '$($toState.DispName)'" #endregion

Additionally, we like to add a hyperlink in the email body that leads the user directly to the related file inside Vault. Such hyperlink must be dynamically created, and these are the according lines:

#region build hyperlink to Vault file
$serverUrl = New-Object  System.uri($vault.AdminService.Url)
$filePath = $file."Full Path"
$filePathUrl = $filePath.Replace("$","%24").Replace("/","%2f").Replace(" ","+")
$fileUrl = $serverUrl.Scheme+"://"+$serverUrl.Host+ "/AutodeskDM/Services/EntityDataCommandRequest.aspx?Vault=Vault&ObjectId=$($filePathUrl)&ObjectType=File&Command=Select"
Add-Log -Text "hyperlink: $fileUrl"
#endregion

That’s it!

Now, in order to try it out, you have to configure the automatic job queuing for the lifecycle transitions you are looking for. This can be done via the LifecycleEventEditor provided by Autodesk. The LifecycleEventEditor is one of the many little secrets of Vault. This tool can be found in the Vault SDK (C:\Program Files (x86)\Autodesk\Autodesk Vault 2015 SDK\util\LifecycleEventEditor). The setup for the SDK can be found on the ADMS Server folder (C:\Program Files\Autodesk\ADMS Professional 2015\SDK) or in the Vault client (C:\Program Files\Autodesk\Vault Professional 2015\SDK). Run the setup and then start the LifecycleEventEditor. You will then select your preferred Lifecycle definition, lifecycle state and transition. Via the “Actions” menu you will be able to add the job to that transition and then commit the changes. The job name is simply the name of your PS1 file without the extension.

LifecycleEventEditor

As you now transition your file from one state to another, then this might be the email that will show up in your inbox:

powerJobs email

Doesn’t it look cool??? So, now that you have the technique, you can extend this job to any other scenario.

Bottom line, with powerJobs it’s super simple to create a new job and thanks to the new commandlets, it’s also very simple to deal with the Vault API, even for unskilled developers!!! Have fun!!

Posted in powerJobs, PowerShell, Vault API | 2 Comments

powerJobs – A new UI experience

We recently released a new version of powerJobs 2015 and talked about on this post. In the past week, we run webcasts where we showed the new features in action. We recorded the whole session, so in case you missed it, you can watch it here: Screencast – What’s new in powerJobs 15.1?

Today, I’d like to highlight one feature in particular, which is the extended JobProcessor UI.

This is how the JobProcessor looks like when delivered by Autodesk:

JobProcessor

And this is how the JobProcessor looks like when started with powerJobs:

powerJobs UI

Underneath the JobProcessor window, you’ll notice an additional window that shows messages. It’s a log or trace window. It shows what is currently happening inside the job. It gives you transparency on the current operations, whether they are successful or facing an issue.

You can also save the logs into a file and send it then to your admin, reseller or to us for further analysis.

Looks good, right? But how does coolOrange do this? Are they changing the Autodesk JobProcessor code? Can I still rely on that thing? Will it change the behavior? What about compatibility?
All good questions, and the answers are simple: don’t worry!

The powerJobs executable is independent from the JobProcessor. The powerJobs.exe either starts the JobProcessor, or accesses a running instance, and simply “takes the screen” of the JobProcessor and embeds it into the powerJobs UI. So, the 2 applications are still independent from each other, however, they look as they are one. This way, no matter which improvements will come with the JobProcessor, powerJobs will not interfere.

Of course, you can run the JobProcessor without the powerJobs UI, and still benefit from the jobs that are delivered with powerJobs, such as the PDF creation or your custom jobs created with PowerShell. However, you will not benefit from the transparency and logging of the trace-window.

So, how do these messages come on the screen? With powerJobs 2015 we released a set of commandlets. Simple commands you can use within your PowerShell scripts. We spoke about this few weeks ago in this post and will talk more in future posts. The commandlet responsible for the logging is the Add-Log. The syntax is super simple:

Add-Log –Text “Your text here…”

Now, you can configure how much information you like to see either in the log-window and/or in the log file. For instance, you can edit the coolOrange.powerJobs.CreatePdfAsAttachment.ps1 file and add some more log messages.

By default, in the log file you will have only warnings, errors, fatal exceptions but no info messages. The Add-Log produces info messages, so by default, such messages will not be reported in the log file. This is intentional, so that as long as there is nothing critical, the log-file should remain almost empty. In case of troubles, the log-file will contain the according information.

In case you like to see more, either in the log-window or in the log-file, you can change the standard settings. Under c:\ProgramData\Autodesk\Vault 2015\Extensions\coolOrange.PowerJobs.Handler you’ll find the file coolOrange.powerJobs.dll.log4net. Just open this file with a notepad. You will find 3 appender sections:

<appender name="OutputDebugStringAppender" ...
<appender name="rollingFile" ...
<appender name="MsgAppender" ...

We are looking for the rollingFile, which is responsible for the log-file, and the MsgAppender, which is responsible for the messages in the log-window. Each appender has a <filter …> where the <levelMin value=”….”> defines what the minimum level of information is that we like to get reported. Now by default, the level for the rollingFile is set to WARN (warnings) so that the INFO messages (more verbose but les less relevant) are not reported to the log file. If you like to have the INFO messages in your log-file as well, just change WARN to INFO, like this:

<filter type="log4net.Filter.LevelRangeFilter">
  <levelMin value="INFO" />
  <levelMax value="FATAL" />
</filter>

In a similar way, you can increase the verbosity of the log-window by editing the levelMin for the MsgAppender filter. By default it is set to INFO, which means that your Add-Log messages and also WARN, ERROR, FATAL would be reported. So this level is pretty good. If you like to see more, you may change it to DEBUG, which would fill up your screen with tons of messages coming from the source code. So, just for fun you may do a test, but you probably will switch back to INFO. Remember to restart powerJobs when you change the log4net file.

So, this is one new feature of powerJobs 2015. Next time I will talk about how to easily create new custom jobs.

Posted in powerJobs, PowerShell | Leave a comment

Our free apps for Inventor – Part V – featureMigrator

The coolOrange featureMigrator allows Inventor users to create part features – like holes – from assembly features more easily.

For example: if you have 2 plates, you can create a hole through both plates on the assembly level. So you know that the hole fits perfectly. But when you open the plate, you would like to see the hole there as well.

Therefore you will migrate the hole into both plates with the featureMigrator.

Like the other coolOrange plug-ins you can download it from the Inventor App Store. The installation is pretty straight forward. Just run the .msi file and follow the instructions.

In the Tools menu of the ribbon in Inventor assemblies, you will find a new command Control.

This will open the featureMigrator-browser. All features are listed there and you can migrate assembly-features by selecting one or several of them. Then, use the Send to Parts command.

At this point, a copy of the original part is made and the feature is moved to this copy. After this step, the original part is replaced with this copy.

Once the operation of migrating features is completed, the featureMigrator will display a dialog that provides information about the results:

This first dialog is a “high-level” report of the migration. It provides the opportunity to select the action for all the assembly features migrated (Suppress if Succeeded, Suppress always, Delete if Succeeded, Delete always or Nothing), and also for the part features that haven’t been migrated correctly (Suppress, Delete or Nothing). Features created by the add-in can be in an invalid state in the parts for a number of reasons.

 

Associativity between part & assembly features

Once you have migrated the feature to the part, the featureMigrator still “remembers” where the feature came from. All the existing features resulting from a migration by the tool are listed in the featureMigrator-browser. If the original feature in the assembly has changed, you can update the feature in the part with the command Update from Assembly in the featureMigrator-browser.

And that’s it!

Have fun with the coolOrange featureMigrator!

Posted in Uncategorized | Leave a comment

Our free apps for Inventor – Part IV – linkParameters

linkParameters allows Inventor users to easily create dependencies between parameters in various parts and sub-assemblies in the context of the top-level assembly within which they reside.

Parameters can be visually selected from a source-component and linked to a specific parameter in a target-component creating the dependency. The mechanism employed is based on the iLogic functionality. It will automatically generate the iLogic code which is required to link the values of the parameters, without the need to manually write any iLogic instructions.

Like the other coolOrange plug-ins you can download it from the Inventor App Store and the installation is pretty straight forward. Just run the msi file and follow the instructions.

In the Manage menu of the ribbon in Inventor assemblies you will get a new command linkParameters in the iLogic section.

For example:  you want the diameter of a part to have the same value as the length of another part in your assembly. Select linkParameters and specify the name of the iLogic rule, which will be created in the background. This first dialog also provides the ability to select an existing rule if any.

Validating this dialog will display the main dialog of the tool:

Select the part with the length as source component and the part with the diameter as target component. Notice that the top-level assembly can also be used as source by checking the upper-left check-box. Drag the source parameter Length on the target parameter Diameter.

By right-clicking the target mappings, they can also be suppressed through a context-menu. An option to automatically map source and target parameters with the same name is also provided from this context menu.

Enjoy coolOrange linkParameters!

Posted in Uncategorized | Leave a comment

Our free apps for Inventor – Part III – pointLinker

Today, we introduce another really helpful tool to you: the pointLinker

Why do you need it? Here’s why:

Inventor can import point data from an Excel file, but once the data has been imported, the link with the Excel file is not retained. If updates to the point data in the Excel file are required, the data must be manually re-imported and the associated model has to be re-constructed. This is time consuming, inefficient and nerve-wracking.

The coolOrange pointLinker plug-in allows Inventor users to import points from an Excel file, retaining a link to that file. Data can be imported (as with the existing command), updated from the Excel file, or mapped to another Excel file.

Like the other coolOrange plug-ins you can download it from the Inventor App Store and easily install it. Just run the msi file and follow the instructions.

In the Tools panel of Inventor, you will find a new command Link Points. When the Link Points command is run, the pointLinker dialog appears. Importing one Excel file will generate one row in the form. You have the option to generate points, lines or connect the points with a spline.

By pressing the Import button, the add-in asks you to select one Excel file. If you select the item, the corresponding entities will be highlighted.

To update or resolve, select the item and right-click. Update will update the item with new date and original Point Type. Resolve will ask you to select another Excel file and import it with its data, with original Point Type.

That’s all, nothing more to it :) Have fun!

Posted in Inventor | Leave a comment

Our free apps for Inventor – Part II – threadModeler

Last week, I talked about our plug-in screenGrab for Inventor 2015. Today, I’d like to introduce our shooting star: threadModeler

You can find it in the “Most Downloaded” section of the Inventor App Store.

The threadModeler has been developed to allow Inventor users to generate a realistic modeled equivalent thread based on an existing Inventor thread feature.

Like all other coolOrange plug-ins you can download it from the Inventor App Store. The installation is again pretty straight forward. Just run the msi file and follow the instructions.

In the Tools menu of the panel in Inventor parts, you will get a new command “threadModeler”.

If you click it, an existing thread feature can be selected in the model browser, which the threadModeler then converts to a realistic 3D modeled thread – based on the underlying thread feature properties.

Modeled threads are accurately generated, saving a lot of time and effort for the user when compared with a manual approach. Your threads simply will look a lot more realistic!

Have fun with the threadModeler!

Posted in Inventor | Leave a comment

Our free apps for Inventor – Part I – screenGrab

So today we’re not talking about Vault or PowerShell, instead we have some treats for the Inventors users among you.

Recently, coolOrange has released 5 free plugin apps for Inventor 2015:

And I am frequently asked what they are doing. All apps have 3 things in common.

1. They are free

2. They can be downloaded from the Autodesk App Store

3. They consist of one feature that makes your work with Inventor easier.

Let me introduce screenGrab

screenGrab can be used within Inventor to simplify image capture of the entire Inventor application window, the graphics view of documents within Inventor, or parts of the graphics-screen.

First, you have to download it from the Inventor App Store (download). The installation is pretty straight forward. Just run the msi file and follow the instructions.

After the installation you will find a new button “Screenshot” in the Tools panel. When you run the Screenshot command, a dialog will appear.

screenGrab

This dialog shows the selection-options and settings. It also displays a preview of the screenshot. The screen will be captured according to the selection options and converted to a relevant bitmap.
You have options to save the bitmap to the clipboard, to a file or send it directly to a printer.

When choosing the “Application” or “Document” option, the borders of the screenshot will be calculated automatically. When using the “Window” option, the user needs to select a region of the screen.

All is pretty easy and intuitive. Try it and have fun!

 

PS: Don’t forget to rate, if you like it!

Posted in Inventor | 1 Comment